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Preface 



This document describes SunCGI, an implementation of the ANSI Computer 
Graphics Interface (CGI) by Sun Microsystems, Inc. Previously, CGI was known 
as the Virtual Device Interface (VDI) standard. Appendix A summarizes the 
differences between SunCGI and ANSI CGI. 

Only certain models within CGI are supported by SunCGI. Specifically SunCGI 
implements input option sets 1, 2, 3, 4, and 6 and output option sets 1 through 6 
of the CGI standard. CGI does not support 3D output primitives. 

The following document was used in interpreting the CGI standard; 

[1] ANSI X3H3 84/45. Irformation Processing Computer Graphics Virtual 
Device Interface (VDI) Functional Description. March 1984. 

The intended reader of this document is an applications programmer who is fami- 
liar with interactive computer graphics and the C programming language. This 
manual contains several example programs that can be used as templates for 
larger SunCGI applications. 
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Introduction 



SunCGI provides access to low-level graphics device functions. SunCGI is use- 
ful for 2D graphics programs that do not require segmentation or transforma- 
tions. The absence of segmentation from SunCGI makes drawing diagrams faster 
and simpler. 

SunCGI provides output primitives, attribute selection, and input device manage- 
ment at a level close to the actual device driver. The output primitives SunCGI 
provides include disjoint polygons, circles, ellipses, and ceU arrays (which can be 
thought of as scaled and transformed pixel arrays). SunCGI'^ large vocabulary of 
attributes include sophisticated pattern filling. SunCGI also provides facilities 
for explicitly binding virtual input devices to physical input devices as well as 
explicit management of an event queue. 



1.1. Using SunCGI 



Following is a SunCGI example application program written in C. 



tinclude <cgidefs.h> 

#define BOXPTS 5 

Ccoor box[BOXPTS] = { 10000,10000 , 

10000,20000 , 
20000,20000 , 
20000,10000 , 
10000,10000 }; 



main { ) 
{ 



name ; 



Cvwsurf device; 

Ccoorlist boxlist; 



/* name of CGI device (set by CGI) */ 
/* device struct (see NORMAL_VWSURF) */ 
/* struct of info for list of points */ 



boxlist. n = BOXPTS; 
boxlist .ptlist = box; 



/* set number of points 

/* set pointer to list of points 



NORMAL VWSURF (device, PIXWINDD);/* view surface is default window 



open_cgi ( ) ; 

open vws(&name, &device) ; 



/* open CGI and the view surface 
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f 


polyline (Sboxlist) ; 
sleep (10) ; 


/* 


watch 


the ' Sl' here! */ 






close vws (name) ; 


/* 


close 


up the view surface and CGI */ 




} 


close_cgi ( ) ; 








/ 



SunCGI uses a variety of structures and enumerated types shown in Appendix B. 
The file <cgidef s . h> should be included in each SunCGI application program 
to provide necessary definitions and constants. 

Here is an example of a command line for compiling box . c to run in the Sun- 
View environment: 



% cc box.c -o box -Icgi -Isunwindow -Ipixrect -Im 
s > 



The order in which the libraries are linked to the program is important. 

AU SunCGI functions can be called by one of two names: the expanded name 
(default) or the C language binding name. See Appendix G for information on 
the list of names for the shorter C language binding. 

As a final note, do not name any user-defined function or variable starting with 
the letters _cgi because doing so may disrupt the internal workings of SunCGI. 

FORTRAN programmers can access SunCGI functions by using the include file in 
cgidefs77.h and linking with the /usr/lib/libcgi77 .a library. 
Details of the FORTRAN interface to SunCGI are provided in Appendix F. 

1.2. The SunCGI Lint 
Library 



SunCGI provides a lint library which provides type checking beyond the capabil- 
ities of the C compiler. For example, you could use the SunCGI lint library to 
check a program called glass . c with a command like this: 



r 




% lint glass. c -Icgi 




k 


J 



Note that the error messages that lint generates are mostly warnings, and may not 
necessarily have any effect on the operation of the program. For a detailed 
explanation of lint , see the lint chapter in the Programmer’s Tools Manuals 
Minibox manual. 

1.3. Overview of SunCGI This section provides an overview of the substance of this manual. The four 

major sections of the manual (which correspond to chapters) are: 

□ view surface initialization and termination (control) 

□ output primitives 

□ attributes 

□ input 
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The overview of these chapters contains a brief introduction to the basic concepts 
of CGI. 

Initialization and Termination Chapter 2 describes functions for the following: 

□ initializing and terminating the entire SunCGI package and individual view 
surfaces 

n defining the coordinate systems 

□ interface negotiation 

□ signal trapping 

The first section in Chapter 2 describes functions for opening and closing view 
surfaces (which are either windows or screens). SunCGI provides facilities for 
writing primitives to multiple view surfaces. Output primitives can be written to 
a selected subset of the open view surfaces by using the activate_vws ( ) and 
deact i vate_vws ( ) fimctions (which turn a view surface on or off without 
closing the view surface or affecting the display). The functions discussed in 
Chapter 2 also define the range of virtual device coordinates (VDC space) and 
device coordinates (screen space). The coordinates of most SunCGI functions 
are expressed in terms of VDC space. The limits of both VDC space and screen 
space can be defined by the application program. 

If you are attempting to run an application program developed on another 
vendor’s version of CGI, negotiation functions are provided that describe the 
capabilities of SunCGI. The application program can use the information 
obtained by using the negotiation functions to call appropriate functions in 
SunCGI to make the application program run correctly. Finally, Chapter 2 
describes SunCGrs option for trapping SIGWHSTCH signals (generated by mani- 
pulating the window environment that the application program is using). 

Output Primitives Chapter 3 describes SunCGI functions for drawing geometrical output primitives 

(for example, polymaikers, polygons, circles, and ellipses) as well as functions 
for performing raster operations. The coordinates of output primitives are 
specified in VDC space (with the exception of some raster functions). Geometri- 
cal output primitives are affected by attributes described in Chapter 4 (such as fill 
style and line width). All output primitives are affected by the drawing mode, 
which determines how an output primitive is affected by pixels that have been 
previously drawn on the screen. 

Attributes Chapter 4 describes the attribute functions that control the appearance of output 

primitives. Attributes can be set individually, or in groups called bundles. The 
use of most attributes is fairly straightforward; fill textures, however, require a 
word of explanation. Geometrical output primitives can be filled with textures 
called hatches or patterns. Hatches are simply arrays of color values with each 
element of the array corresponding to a pixel. Patterns are arrays of color values 
which can be scaled and translated. 
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Input 



Errors 



Programming Tips 



Appendices 



Qiapter 5 describes the standard interface SunCGI offers for receiving input from 
the mouse and the keyboard. The CGI input model is based on the logical input 
device model in GKS. In this system, a logical input device (for example, a 
LOCATOR device), is bound to a jAysical device (for example, the x-y position 
of the mouse) called a trigger. Triggers may be associated with logical input 
devices by the application program. Each logical input device has an associated 
measure (for example, the measure of a LOCATOR device is the mouse position 
on the screen). Each logical input device also has a state which determines how 
a device handles input. Each logical input device can be in one of five states: 

□ RELEASED (uninitialized) 

□ NO_EVENTS (initialized but unable to receive input) 

□ REQUEST_EVENT (waiting for one event) 

□ RESPOND_EVENT (report one event asynchronously) 

□ QUEUE_EVENT (put each event at the end of the event queue) 

Errors are reported in SunCGI by setting the return value of the function to a 
nonzero result and echoing an error message and number on the terminal. How- 
ever, error trapping can be controlled by the set_error_warning_mask ( ) 
function. An explanation of each error message (and suggestions for how to 
eliminate them) is presented in Appendix C. 

For novice C language users, the syntax of SunCGI may pose some initial 
difficulties. When a pointer is specified as an argument to a SunCGI function, 
SunCGI usually expects space to be allocated by the application program and the 
function argument to be preceded by an ampersand (&). SunCGI uses many 
enumerated types. These types are printed by the printf { ) function as 
integers. If you want to print out these values in English, you should use the 
enumerated types as indices into a character array which contains appropriate 
English equivalents of the enumerated types. Finally, if you are a novice pro- 
grammer, copy the example programs in Appendix D and use them as templates 
to build your own program. Further help can be obtained by referring to the 
tables at the end of Appendix C. These tables list commonly encountered prob- 
lems and how to solve them. 

The first four appendices are intended to make SunCGI easier to understand. 
Appendix A lists the ANSI CGI standard functions not implemented by SunCGI 
and the SunCGI functions not part of the ANSI CGI standard. Appendix B pro- 
vides the type definitions used by the SunCGI functions. Appendix C lists the 
error messages and possible strategies for eliminating them. Appendix C also 
lists possible causes of simple run-time errors. Appendix D describes sample 
programs. 

Appendices E and F describe the interfaces between SunCGI and other Sun 
software packages: SunView and FORTRAN. Appendix E explains how to call 
SunCGI from application programs written on top of SunView. This interface 
allows SunCGI to write output primitives in different windows using different 
attributes. 
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1.4. References 



Appendix F describes the interface to the FORTRAN programming language. 

The behavior of each SunCGI function is the same in both C and FORTRAN. 

The final appendix. Appendix G, describes the SunCGI C binding for CGI. These 
names are contained in the header file <cgicbind . h>, which must be included 
in an application program using the short C binding. 

[1] ANSI X3H3. Computer Graphics Virtual Device Interface. March 1984. 

[2] Conrac Corporation. Raster Graphics Handbook, Second Editioa Van 
Nostrand Reinhold, 1985. 

[3] J.D. Foley and A. van Dam. Fundamentals of Interactive Computer 
Graphics. Addison-Wesley, 1982. 

[4] B.W. Kemighan and D.M. Ritchie. The C Programming Language. 
Prentice-Hall, 1978. 

[5] W.M. Newman and R.F. SprouU. Principles of Interactive Computer 
Graphics. McGraw-HiU, 1979. 

[6] V.R. Pratt. Standards and Performance Issues in the Workstation Market. 
IEEE Computer Graphics and Applications, April 1984. 

[7] SunView I Programmer's Guide. Sun Microsystems. 

[8] SunView I System Programmer' s Guide. Sun Microsystems. 

[9] Pixrect Reference Manual. Sun Microsystems. 

[10] SunCore Reference Manual. Sun Microsystems. 

[11] FORTRAN Programmer' s Guide for the Sun Workstation. Sun Microsys- 
tems. 
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Initializing and Terminating SunCGI 



The current CGI standard does not provide functions for initializing and terminat- 
ing devices. ANSI CGI is intended to provide an interface for a single view sur- 
face (one per CGI instance). SunCGI extends CGI into the window environment 
by allowing a single CGI process to control multiple view surfaces. Six nonstan- 
dard functions, open_cgi { ) , close_cgi ( ) , open_vws ( ) , 
close_vws ( ) , activate_vws ( ) , and deactivate_vws ( ) , are 
included in SunCGI. open_cgi ( ) and close_cgi ( ) initialize and ter- 
minate the operation of the SunCGI package, open vws ( ) and 
close_vws ( ) initialize and terminate a view surface. activate_vws () 
activates the view surface. deactivate_vws ( ) restricts output primitives 
from a view surface. 

SunCGI is capable of handling up to five view surfaces at once. 

2.1. View Surface A view surface is automatically activated when it is opened. However, a view 

Initialization and surface can be deactivated (with the deactivate_vws ( ) function) when the 

Selection output stream is not intended to appear on all view surfaces. Subsequent calls to 

SunCGI output functions wiU not apply to deactivated view surfaces, until 
activate_vws ( ) is called again (see the following example). However, 
inputs can be received on deactivated view surfaces. 



tinclude <cgidefs.h> 

ma in ( ) 

{ 



Ccoor 


11, 


/* 


coord of lower-left corner of rectangle 


*/ 




ur. 


/* 


coord of upper-right corner of rectangle 


*/ 




center; 


/* 


coord of center of circle 


*/ 


Cint 


namel. 


/* 


name of first CGI view surface 


*/ 




name2 , 


/* 


name of second CGI view surface 


*/ 




radius ; 


/* 


radius of circle 


*/ 


Cvwsurf 


device 1, 


/* 


1st CGI device struct (see NORMAL_VWSURF ) 


*/ 




device2 ; 


/* 


2nd CGI device struct (see NORMAL VWSURF) 


*/ 



static Cchar *scrn_name = ”/dev/fb"; 

char *toolposition = "0,0,250,250,0,0,250,250,0”; 



11.x = 11. y = 5000; /* set rectangle coordinates */ 

ur.x = ur.y = 15000; 
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center.x = center.y =10000; /* set circle coordinates */ 

radius = 5000; 



NORMAL_VWSURF (device 1, PIXWINDD) ; /* 
NORMAL_VWSURF (device2, PIXWINDD); /* 
device2 .flags = VWSURFJSTEWFLG; /* 
device2.ptr = fitoolposition; /* 



set up a default window */ 
set up a 2nd default window */ 
don't take over current window */ 
set position and size of 2nd */ 



open_cgi(); /* open CGI and view surfaces */ 

open_vws (Snamel, sdevicel) ; 
open_vws (&name2, &device2) ; 



rectangle (& 11, &ur) ; / 

deactivate_vws (name2) ; / 

circle (Scenter, radius); / 

activate vws(name2); / 



circle (Scenter, 2*radius) ; / 



rectangle draws on both devices */ 
only display one is acive now */ 
draw circle on device one only */ 
both displays active again */ 
circle draws on both devices */ 



sleep (20) ; 

close_vws (namel) ; /* close view surfaces and CGI */ 

close_vws (name2) ; 
close_cgi () ; 



Cerror open_cgi() 

open_cgi ( ) initializes the state of SunCGI to CGOP (CGi OPen). 
open_cgi { ) does not initialize input devices but does initialize the event 
queue. No other CGI functions can be used without generating an error if 
open_cgi ( ) has not been called. SunCGI traps various signals as described in 
Section 2.3. 

ENOTCGCL [1] CGI not in proper state: CGI shall be in state CGCL. 

T able 2-1 SunCGI Default States 



State 


Value 


Range ofVDC space 


0-32767 in both x and y directions 


Clip Indicator 


CLIP 


Clip Rectangle 


Range of VDC space 


Error Warning Mask 


INTERRUPT 


Input Devices 


Uninitialized 


Input Queue 


EMPTY 


Trigger Associations 


Defaults specific values listed in Table 5-2 


Echo Modes 


Device specific values listed in Table 5-3 



Open CGI (SunCGI 
Extension) 
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You may be unfamiliar with some of the entries discussed in Table 2-1. How- 
ever, these concepts are explained in the course of this chapter. Further, each of 
these concepts are referenced in the index. 

Open View Surface (SunCGI Cerror Open vws (name, devdd) 

Extension) Cint *name; /* name assigned to cgi view surface */ 

Cvwsurf *devdd; /* view surface descriptor */ 

open_vws ( ) initializes a view surface. The list of available view surfaces is 
described in Table 2-2. open_vws ( ) initializes the attributes to their default 
values (listed in Table 2-3). The returned argument name is the identifier which 
is used to refer to this view surface in other SunCGI functions. To reinitialize the 
state of the view surface without reopening it, use the hard_reset ( ) function. 

A maximum of five view surfaces may be open at one time. Output primitives 
are displayed on all active view surfaces (view surfaces must be opened before 
they are activated). However, input is only echoed on the view surface pointed 
to by the mouse. Most of the Cvwsurf fields should be zeroed, as by the 
NORMAL_VWSURF macro. Set the view surface type by assigning the dd (device 
driver) element of the devdd argument to the name of the appropriate device 
driver as in this example:^ 

Cvwsurf device; 

NORMAL_VWSURF (device, BW2DD); 
open_vws (Sname, Sdevice) ; 

NOTE The NORMAL_VWSURF macro initializes the dd element of the Cvwsurf struc- 
ture and guarantees that the view surface will be opened in the normal fashion. 
However, to open a window with some nonstandard parameters, or to open a 
second window from a graphics tool, read the following paragraphs. To use an 
existing Pixwin, skip the following paragraphs and read Appendix E instead. 

If the view surface of the specified type has been previously initialized and the 
type of view surface is a window (PIXWINDD or CGPIXWINDD), a CGI tool (a 
window with the name CGI Tool) is opened. Other characteristics of the view 
surface can be defined by setting the other elements of the devdd argument 
(which is of type Cvwsurf). 



^ Notice that when SwiCGI specifies a pointer it usually requires that the argum^t is prefaced by an & 
character when the argument is actually used. 
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typedef struct { 

char screenname [DEVNAMESIZE] ; 

char windowname [DEVNAMESIZE] ; 

int windowfd; 

int retained; 

int dd; 

int cmapsize; 

char cmapname [DEVNAMESIZE] ; 
int flags; 
char **ptr; 

} Cvwsurf; 



/* physical screen */ 

/* window */ 

/* window file descriptor 
/* retained flag */ 

/* device */ 

/* colormap size */ 

/* colormap name */ 

/* new flag */ 

/* CGI tool descriptor */ 



The elements screenname and windowname specify alternate screens (for exam- 
ple, IdevIcgoneO) or alternate windows (for example, IdevlwinlO). If these ele- 
ments are left blank, the current screen and the current window are used, unless 
the dd field implicitly specifies a device (for example, CGIDD). The element 
windowfd is the window file descriptor for the current device. The current imple- 
mentation of SunCGI ignores this element. 

If the element retained is nonzero, then the view surface created by 
open_vws ( ) has a retained window associated with it (that is, if the window is 
covered up by another window and then revealed, the picture present before the 
window was covered-up will be redisplayed. By default the window created by 
open_vws ( ) is non-retained. That is, if the window is covered-up and then 
revealed, the covered-portion will be redisplayed as white. However, drawing in 
non-retained windows is twice as fast as drawing in retained windows, so the 
choice of which type of view surface to open should be carefully considered. 

The dd element specifies the view surface type. The cmapsize and the cmapname 
elements determine the size and the name of the colormap. No colormap is 
enabled for monochrome devices. The colormap determines the mapping 
between color indices and red, green, and blue values. If the colormap specified 
by the cmapname element of the devdd argument is the same as a colormap seg- 
ment which already exists, then the colormap segment is shared, cmapsize 
should be a power of two, less than or equal to 256. The cmapsize and the cmap- 
name fields provided in the Cvwsurf stracture that is passed to open_vws ( ) 
must be initialized to modify the colormap. 

See Chapter 4, section 4.9, for a description on using colormaps in SunCGI. For 
more information about colormaps in CGIPW, refer to the SunView 1 
Programmer’s Guide. 

SunCGI must define its own colormap by creating a new colormap or using a 
shared colormap whether the SunCGI application is running inside or outside the 
window system. 

The SunCGI color intensity scheme ranges from 0 to 255. 

In SunCGI, first set the dd element of the view surface stmcture to be the frame 
buffer type {CGIDD, CG2DD, CG4DD, GPIDD, or CGPIXWINDD}. In the win- 
dow environment, the graphics processor is accessed through CGPIXWINDD. If 
the graphics processor is available, the CGPIXWINDD uses the device for 
transformation calculations. Within the view surface stracture, set the cmapsize 
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element to the colormap size, and the cmapname element to the string that names 
the colormap. When the view surface is opened, and the red, green, and blue 
color arrays are initialized, the colormap array of type Ccentry points to the 
red, green, and blue color arrays. 

When the flags element is nonzero, no attempt is made to take over the current 
graj^cs subwindow (if one exists). If this flag is set or the graphics subwindow 
has already been taken over by SmCGI, then a CGI Tool (a window with the 
name View Surface Tool) is created. The ptr element specifies the size and 
placement of the CGI Tool, ptr is a pointer to an array of strings, only the first of 
which is currently used. This string should consist of nine decimal numbers 
separated by commas. The array takes the following form: 

"nl, nt, nw, nh, il, it, iw, ih, I" 



Each element of the array should be filled with an integer. The first two elements 
specify the x and y coordinates of the upper left-hand comer of the CGI Tool in 
screen, or Pixwin coordinates. This coordinate system specifies the upper left- 
hand corner as the origin, so be sure that the y value for the upper comer given 
is less than the value for the lower comer. The third and fourth elements specify 
the width and height of the CGI Tool. The fifth through eighth elements specify 
the position and size of the iconic form of the CGI Tool. If the ninth element is 
nonzero, the tool is displayed in its iconic form. 



ENOTOPOP [5] 

ENOWSTYP [11] 
EMAXVSOP [12] 
EMEMSPAC [110] 
ENOTCCPW [112] 



CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Specified view surface type does not exist 
Maximum number of view surfaces already open. 

Space allocation has failed. 

Function or argument not compatible with CGBPW mode. 



SunCGI distinguishes between the inside and the outside of the window system. 
While running under sunt ools , SunCGI uses different window devices as the 
view surface. 



The color view surfaces for the window system are the ’color graphics pixwins,’ 
called cgpixwindds. SunCGI, while running inside the window system, uses 
cgpixwindds or gppixwindds. While running outside the window system, 
SunCGI uses the raw frame buffer. These devices are described in the following 
table. 
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Table 2-2 Available SunCGI View Surfaces 



dd Element 
of View Surface 


Name 


Description 


1 


BWIDD 


The Sun 1 monochrome frame buffer 
device; and for Sun 2 multibus systems 
when mnning outside suntools, in 
console mode. 


2 


BW2DD 


The Sxm 2 VME and Sun 3 monochrome 
frame buffer device when running out- 
side suntools, in console mode. 


3 


CGIDD 


The Sun 1 color frame buffer device; 
and for Sun 2 multibus systems when 
running outside suntools, in console 
mode. 


4 


BWPIXWINDD 


A monochrome window, when ranning 
the application in a suntools win- 
dow, or in a SunView canvas subwin- 
dow, as in the case for CGIPW. 


5 


CGPIXWINDD 


A color window, when running the 
application in a suntools window; or 
in a SunView canvas subwindow, as is 
the case for CGIPW. 


6 


GPIDD 


The graphics processerf when running 
the application outside suntools, in 
console mode. 


7 


CG2DD 


The Sun 2 and Sun 3 color frame device 
when ranning outside suntools, in 
console mode. 


8 


CG4DD 


The Sun 3/110 color frame buffer device 
when ranning outside suntools, in 
console mode. 


9 


PIXWINDD 


A monochrome or color window, when 
running the application in a suntools 
window, or in a SunView canvas 
subwindow as in the case of CGIPW. 

Use this device when you are not sure 
whether you will have a monochrome or 
color monitor. 



t The graphics processor is Sun’s hardware graphics accelerator. This is 
a single board option. An additional graphics buffer board option may 
also be added at a later time. 
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T able 2-3 View Surface Default States 



State 


Value 


View Surface 


Cleared 


Device Viewport 


View Surface 



NOTE Most failures during the opening of a view surface result in error ENOWSTYP 

[ 11 ] . The most common reason is missetting (or failing to set) the dd element 
of the Cvwsurf structure. For example, opening a device surface type 
PIXWINDD instead cf CG’PIXVUUDD on a color pixwin, or using CG2DD when 
a Idevicgtwo surface is being used by suntools. The NORMAL_VWSURF 
macro should be used to initialize this structure. 



Activate View Surface 
(SunCGI Extension) 



Cerror activate_vws (name) 

Cint name; /* view surface name */ 

activate_vws ( ) activates the view surface specified by name. Subsequent 
SunCGI calls affect this view surface. Nothing is displayed on a view surface 
unless that view surface is active. Since a view surface is active as soon as it is 
opened, activate_vws { ) is only needed to reactivate a deactivated view sur- 
face. Note that activating a view surface may reset the state of SunCGI. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 


EVSIDINV [10] 


Specified view surface name is invalid. 


EVSNOTOP [13] 


Specified view surface not open. 


EVSISACT [14] 


Specified view surface is active. 



Deactivate View Surface 
(SunCGI Extension) 



Cerror deactivate_vws (name) 

Cint name; /* view surface name */ 



deactivate_vws ( ) prevents calls to SunCGI functions from having an effect 
on this view surface. The view surface may be reactivated by 
activate vws ( ) at a later time without having to be reopened. Note that 
deactivating a view surface may reset the state of SunCGI. 



ENOTVSAC [4] 
EVSIDINV [10] 
EVSNOTOP [13] 
EVSNTACT [15] 



CGI not in proper state: CGI shall be in state VSAC. 
Specified view surface name is invalid. 

Specified view surface not open. 

Specified view surface is not active. 



Close View Surface (SunCGI Cerror close_vws (name) 

Extension) cint name; /* view surface name */ 

close_vws ( ) terminates a view surface. Future SunCGI calls have no effect 
on this view surface. The view surface cannot be reactivated without being reo- 
pened. 
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ENOTOPOP [5] 

EVSIDINV [10] 
EVSNOTOP [13] 
ENOTCCPW [112] 



CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Specified view surface name is invalid. 

Specified view surface not open. 

Function or argument not compatible with CGIPW mode. 



Cerror close_cgi{) 

close_cgi ( ) terminates aU open view surfaces and restores the state of the 
SunView to the state that it was in before SunCGI was opened. Future SunCGI 
calls will have no effect and will generate errors. 

A call to close_cgi ( ) should be included in the exit routines of an applica- 
tion program to guarantee leaving the SunView and SunCGI in a stable state. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

ENOTCCPW [112] Function or argument not compatible with CGIPW mode. 

2.2. View Surface Control The functions described in this section perform the following: 

□ define the range of world and device coordinates 

□ control clipping 

□ reset selected aspects of the view surface and the internal state of SunCGI. 

Most functions in SunCGI express coordinates in VDC space (Virtual Device 
Coordinate space). In conventional computer graphics terms, VDC space 
corresponds to world coordinate space. The mapping between VDC space and 
screen space is determined by the physical size of the screen in pixels. Screen 
space is set by default to the entire size of the screen or the graphics window 
depending on the device type. The mapping from VDC space to screen space is 
always isotropic (the shape of the rectangle defining screen space is the same 
shape as VDC space). Therefore, VDC space defines the shape of the active view 
surface. The portion of screen space which does not correspond to VDC space is 
ignored. The aspect ratio (the ratio between the height and width) is therefore, 
defined by VDC space and not screen space. 



Close CGI (SunCGI 
Extension) 



VDC Extent Cerror vdc_extent (cl, c2) 

Ccoor *cl, *c2; /* bottom left-hand and */ 

/* top right-hand corner of VDC space */ 

vdc_extent ( ) defines the limits of VDC space. The range of the coordinates 
must be between -32767 and 32767 (or an error is generated). VDC space can be 
set by the application program, but it ranges from 0 to 32767 in both the x and 
the y directions by default. Resetting VDC space impacts the display of output 
primitives on all view surfaces. 

Resetting the limits of VDC space automatically redefines the clipping rectangle 
to the new limits of VDC space, regardless of the value of the clip indicator. 
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Changing the mapping from screen space to VDC space allows for translation 
(move) or scaling (zoom in/zoom out) of output primitives. However, no rota- 
tion runctions are pioviucu uy , oiiu uicrcforc, niust he supplied in the 

application program. The code fragment below translates and zooms in on a rec- 
tangle. 



ENOTOPOP [5] 

EBADRCTD [20] 
EVDCSDIL [24] 
ENOTCCPW [112] 



CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Rectangle definition is invalid. 

VDC space definition is illegal. 

Function or argument not compatible with CGIPW mode. 



tinclude <cgidefs.h> 

main () 

{ 

Cvwsurf device; 

Cint name; 

Ccoor dvl, dv2, lower, upper; 

NORMAL_VWSURF (device, PIXWINDD) ; 
open_cgi ( ) ; 

open_vws (&name, &device) ; 
dvl.x = dvl.y = 0; 

dv2,x = dv2.y = 200; /* coord, space (0<x|y<200) */ 

vdc_ext ent ( & dvl , & dv 2 ) ; 



lower. X = lower. y = 30; 
upper. X = upper. y = 70; 
rectangle (Supper, Slower); 
sleep (4) ; 

dvl.x = dvl.y = 0; 
dv2.x = dv2.y = 100; 
vdc_ext ent ( Sdvl , S dv2 ) ; 
rectangle (Supper , Slower); 
sleep (4) ; 

dvl.x = dvl.y = 20; 
dv2.x = dv2.y = 80; 
vdc_extent (Sdvl , Sdv2) ; 
rectangle (Supper , Slower); 
sleep (20) ; 

close_vws (name) ; 
close_cgi () ; 



/* rectangle coordinates */ 

/* draw initial rectangle */ 

/* coord, space (0<xly<100) */ 
/* center rectangle */ 



/* coord, space (20<xly<80) */ 
/* enlarge rectangle */ 



microsystems 



Revision A, of 9 May 1988 






Device Viewport 



Cerror device_viewport (name, cl, c2) 

Cint name; /* name assigned to cgi view surface */ 

Ccoor *cl, *c2; /* bottom left-hand and top right-hand */ 

/* corner of view surface to map */ 

/* device (expressed in pixels) */ 

device_viewport ( ) redefines the limits of screen space. The coordinate 
values specified are in pixels and are in the screen’s coordinate system, which has 
its origin in the upper left-hand comer of the screen. If the new limits are not 
less than or equal to the size of the current screen or window size, an error is 
returned. Although device_viewport ( ) does not redefine the aspect ratio, 
it may redefine which areas of the screen are unused. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 

VSOP,orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [ 13] Specified view surface not open. 

EBADRCTD [20] Rectangle definition is invalid. 

EBDVIEWP [21] Viewport is not within Device Coordinates. 

ENOTCCPW [112] Fimction or argument not compatible with CGIPW mode. 

Clip Indicator Cerror clip_indicator (cflag) 

Cclip cflag; /* CLIP, NOCLIP or CLIP_RECTANGLE */ 

The value of the argument cflag determines whether output primitives are clipped 
within the viewport before they are displayed. The default state is (XIP. The 
advantage of turning clipping off is that it improves the speed of drawing primi- 
tives. However, if clipping is set to N(XLIP, SunCGI may draw output primi- 
tives outside of the window or within the bounds of an overlapping window. The 
application is responsible for placing the object within the limits of the display 
rectangle. Drawing outside the display rectangle can result in unpredictable 
results, including system errors. 

If clipping is not NOCLIP, output primitives are clipped to either the clip rectan- 
gle (if cflag equals CLIP_RECTANGLE), or the fiiU extent of VDC space (if cflag 
equals CLIP). The extent of VDC may be set with the vdc_extent ( ) function. 

typedef enum { 

NOCLIP, 

CLIP, 

CLIP_RECTANGLE 
} Cclip; 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

ENOTCCPW [112] Function or argument not compatible with CGIPW mode. 
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Clip Rectangle 



Hard Reset 



Reset to Defaults 



Clear View Surface 



Cerror c lip_rect angle (xmin, xmax, ymin, ymax) 

Cint xmin, xmax, ymin, ymax; /* bottom left-hand and top */ 

/* right-hand corner of clipping 
/* rectangle */ 



clip_rectangle ( ) defines the clipping rectangle in VDC space, to be used 
when the clip indicator is set to CL1P_RECT ANGLE. By default, the clipping 
rectangle is set to the borders of VDC space. The clipping rectangle is automati- 
cally reset by vdc_extent ( ) . 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 



EBADRCTD [20] 
ECLIPTOL [22] 
ECLIPTOS [23] 
ENOTCCPW [112] 



Rectangle definition is invalid. 

Qipping rectangle is too large. 

Qipping rectangle is too small. 

Function or argument not compatible with CGIPW mode. 



Cerror hard_reset() 

Device control functions restore the view surface and the internal state of 
SunCGI to a known state. The individual aspects of the device which can be 
reset are the output attributes, the view surface (screen), and the error reporting. 

hard_reset ( ) returns the output attributes to their default values: it ter- 
minates all input devices, empties the event queue, and clears all view surfaces. 
VDC space is reset to its default values and the clip indicator is set to CLIP. This 
function should be used sparingly because most control, attribute, and input func- 
tions called before this function will not have any effect on functions called after 
hard_reset{) is called. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Cerror reset_to_def aults ( ) 

reset_to_defaults ( ) returns output attributes to defaults (see Table 4-1). 
reset_to_def aults ( ) does not clear the screen, reset the input devices, or 
reset the character set index. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

Cerror clear_view_surf ace (name, defflag, index) 

Cint name; /* name assigned to cgi view surface */ 

Cflag defflag; /* default color flag */ 

Cint index; /* color of cleared screen */ 

clear_view_surf ace ( ) changes all pixels in the relevant area of the view 
surface specified by name to the color specified by the index argument, unless the 
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Clear Control 



Set Error Warning Mask 



d^ag argument is set to OFF. If defflag is equal to OFF, the view surface is 
cleared to color zero. The area of the view surface which is actually cleared is 
determined by the clear_control ( ) function. 

clear_view_surf ace ( ) also resets the internal state of SunCGI according 
to previous calls to the clear_control ( ) function. 

clear_view_surf ace ( ) resets the current background color to the color of 
the cleared view surface. 



ENOTVSAC [4] 
EVSIDINV [10] 
EVSNOTOP [13] 
EVSNTACT [15] 
ECINDXLZ [35] 
EBADCOLX [36] 



CGI not in proper state: CGI shall be in state VSAC. 
Specified view surface name is invalid. 

Specified view surface not open. 

Specified view surface is not active. 

Color index is less than zero. 

Color index is invalid. 



Cerror clear_control (soft , hard, intern, extent) 

Cacttype soft, hard; /* soft and hard copy actions */ 
Cacttype intern; /* internal action */ 

Cexttype extent; /* clear extent */ 

clear_control ( ) determines the action taken when 
clear_view_surf ace ( ) is called. The argument soft can be set to either 
NO_OP or CLEAR. The argument hard, which regulates clearing rules for 
plotters, is ignored (because SunCGI does not currently support hard-copy dev- 
ices) and is included only for ANSI CGI compatibility. The argument intern is set 
to either RETAIN or (XEAR. This parameter was included to support segmenta- 
tion storage, which is not currently a part of ANSI CGI. Therefore, the intern 
argument is ignored. The argument extent determines what area of the screen is 
cleared. It is set to one of the values in the Cexttype enumerated type: 

typedef enum { 

CLIP_RECT, 

VIEWPORT, 

VIEWSURFACE 
} Cexttype; 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

ENOTCCPW [112] Function or argument not compatible with CGEPW mode. 

Cerror set_error_warning_mask (action) 

Cerrtype action; /* action on receipt of an error */ 

set_error_warning_mask ( ) ^ determines the action taken by SunCGI 
when an error occurs. Three types of action are possible: NO_ACTION, POLL, 



^ The syntax of set error warning mask ( ) in SunCGI is slightly different from the proposed ANSI 
standard in that the ANSI definition allows different actions for different classes of errors. 
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INTERRUPT. If the action argument is set to NO_ACTION, errors are detected 
internally, but not reported. The error number is returned to the caller of a CGI 
routine. The user is advised not to set the action argument to NO_ACTION. 

POLL and INTERRUPT actions print an error message on the terminal, and also 
return the error number (see Appendix C) so the program can perform exception 
handling. The default set_error_warning_mask { ) is INTERRUPT. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 



Table 2-4 Error Warning Masks 



Error 

Warning Mask 


Message 

Printed 


Program 

Aborted 


Error 

Number Returned 


NO ACTION 


No 


No 


Yes 


POLL 


Yes 


No 


Yes 


INTERRUPT 


Yes 


FATAL errors! 


Non-FATAL errors 



t SunCGI defines no errors as FATAL. AU errors are non-fatal 
so the application has complete control to abort or perform other 
processing as desired. Therefore, POLL and INTERRUPT are the 
same in SunCGI. 

2.3. Running SunCGI with SunCGI always traps five signals: SIGINT, SIGCHLD, SIGIO, SIGHUP and 

Sun View SIGWINCH. The first four of these cause SunCGI cleanup and program termina- 

tion. When using a Graphics Processor option, SunCGI also traps SIGXCPU. All 
registered signal handlers are called when its respective signal occurs. Be careful 
that the actions performed by one signal handler do not interfere with the actions 
performed by another signal handler, including SunCGFs. The Notifier is an 
example of a signal handler that must be coordinated in this way. 

Unless a SunCGI application program has opened a retained view surface, over- 
lapping another window onto a graphics subwindow will destroy the picture 
below. SunCGI programs can regenerate a display surface by trapping the 
SIGWINCH (SIGnal WINdow CHange) signal. 

It is possible (though unsupported) to install a signal handler for signals after cal- 
ling open_pw_cgi ( ) (see Appendix E). Since these signal handlers replace 
SunCGFs handler, the application should save SunCGVs signal handler (returned 
by signal), and call the saved handler when the signal occurs (amid the user’s 
own processing). Because the response of the program to the signal then depends 
on the place in the user’s own signal handling that SunCGFs handler is called, 
results are unpredictable, and may change with a new version of SunCGI. 

Note that it is not necessary for an application to catch a SIGWINCH signal, since 
SunCGFs set_up_sigwinch ( ) routine offers an easier interface. A user’s 
sig function { } has a different calling semantics from a SIGWINCH in that 
pw_damaged ( ) and pw_donedamaged ( ) have already been invoked. 
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When a window’s contents needs regeneration during execution time, the process 
associated with a window receives a SIGWINCH signal. The application can use 
this signal to determine when a view surface needs to be regenerated. 

NOTE Under no circumstances will the user be able to access the SIGWINCH signals 
generated when a view surface is initialized. 

When a window obstructs a SunCGI view surface, output to that view surface is 
normally clipped to the exposed portion only (unless the clip indicator is 
NOCLIP). When the obstmction is removed, unless the window is RETAINED, 
the picture must be regenerated by re-running the output generation of the appli- 
cations, for that view surface at least. An application’s SIGWINCH handling 
function is called for this purpose. 

When a SunCGI window’s size changes during execution, the picture must be 
regenerated. But first, SunCGI updates the transformation used to map VDC 
space into screen space. Then, if the affected view surface is RETAINED, the 
retained copy is rewritten onto the view surface. (Because of the size change, 
this may not repair the damage satisfactorily.) Lastly, the application’s 
SIGWINCH function is called. 



Set Up SIGWINCH (SunCGI 
Extension) 



Cerror set_up_sigwinch (name, sig_function) 

Cint name; 

Cint (*sig_f unction) () ; /* signal handling function */ 

set_up_sigwinch { ) allows the application program to trap SIGWINCH sig- 
nals for view surface name, s ig_f unct ion ( ) is a pointer to a function 
returning an integer. If sig_f unction ( ) is nonzero, all SIGWINCH signals 
that are not trapped by the internals of SunCGI (from view surface initialization) 
are passed to the function specified by sig_f unction ( ) . 

The sig_f unction ( ) is called when the SIGWINCH signal is received. It is 
the programmer’s responsibility to use a flag to determine if it is safe to process 
the signal at this time, or to set a flag indicating that signal processing has been 
put off until later. See the SunView I Programmer* s Guide for information on 
SIGWINCH handling. 

The sig_f unction { ) argument is called with a single argument: the name of 
the view surface with which it is associated by the call to 
set_up_sigwinch ( ) . This allows more than one view surface to share the 
same sig_f unction { ) , and differentiate which view surface needs redisplay. 

ENOTOPOP [5] CGI not in proper state; CGI should be in state CGOP, 
VSOP, orVSAC. 

Following is an example of a program that uses set_up_sigwinch ( ) . 
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— 

tinclude <cgidefs.h> 

Ccoor box[5] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 }; 

Cint name; 

extern Cint redraw () ; 

Cvwsurf device; 

main ( ) 

{ 

Ccoorlist boxlist; 

boxlist.n = 5; 
boxlist .ptlist = box; 

NORMAL_VWSURF (device, PIXWINDD) ; 

open_cgi ( ) ; 

open_vws (Sname, &device) ; 
set_up_sigwinch (name, redraw); 

polyline (Sboxlist) ; 
sleep (10) ; 

close_vws (name) ; 
close_cgi () ; 

} 

Cint redraw 0 
{ 

clear_view_surf ace (name, ON, 0); 

} 

^ > 



2.4. Interface Negotiation CGI is intended to support a ‘negotiated device interface’, allowing hardware- 

specific programs written to run on other machines. SunCGI only allows inquiry 
of most of the settable modes.^ You may want to find out which types of input 
devices are supported. However, functions for setting color precision, coordinate 
type, specification mode, and color specification are not provided because 
SunCGI only supports one type of color precision (8-bit), coordinate type 
(integers), and color specification (indexed). The width and size specification 
modes are settable; the functions that set them are described in Chapter 4. The 
inquiry negotiation functions are supported so that an application program writ- 
ten for a CGI on another manufacturers’ workstation can find out whether the 
SunCGI is capable of running that application. 

^ The functions not supported by SunCGI are classified as non-required by the March 1984 ANSI CGI 
standard. See Appendix A. 
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Inquire Device Identification 



Inquire Device Class 



Inquire Physical Coordinate 
System 



Cerror inquire_device_identif ication (name, devid) 

Cint name; /* device name */ 

Cchar devid [DEVNAMESIZE] ; /* workstation type */ 

inquire_device_identification ( ) reports which type of Sun Works- 
tation view surface name is associated with. The argument devid may be set to 
one of the Sun Woikstation types described in Table 2-2. The inclusion of the 
name argument deviates from the ANSI standard, but is necessary so that the 
characteristics of individual view surfaces may be inquired. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

E VS I D INV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 



Cerror inquire_device_class (output, input) 

Cint *output, *input; /* output and input abilities */ 

inquire_device_class ( ) describes the capabilities of Sun Workstations 
in terms of the CGI functions they support."^ Each of the two returned values 
reports the number of functions of each of the two classes that are supported in 
SunCGI. These numbers (the values of iryyut and output) are used to make more 
detailed inquiries by using functions inquire_input_capabilities ( ) 
and inquire_output_capabilities () . 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 



Cerror inquire_physical_coordinate_system (name, xbase, 
ybase, xext, yext, xunits, yunits) 

Cint name; /* name assigned to cgi view surface 

Cint *xbase, *ybase; /* base coordinates */ 

Cint *xext, *yext; /* pixels in x and y directions */ 

Cfloat *xunits, *yunits; /* number of pixels per mm. */ 

inquire_phy sical_coordinate_system ( ) reports the physical 
dimensions of the coordinate system of view surface name in pixels and millime- 
ters. inquire_physical_coordinate_system ( ) is provided to permit 
the drawing of objects of a known physical size. 

inquire_phy sical_coordinate_system ( ) is also provided to assist 
in the computation of parameters for the device_viewport ( ) function. 

xbase and ybase are expressed in the screen coordinate system and are therefore 
given in pixels, meaning they have the upper left-hand corner of the screen as 
their origin, xext and yext describe the maximum extent of the window in which 
the application program is run. (The window may or may not cover the entire 
screen.) The number of pixels per millimeter is always set to 0 because the 
actual screen size of device varies between individual monitors. The actual size 



The output argumoit does not include the non-standard CGI functions. 
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of the screen may be obtained from the number of pixels in the x and y directions 
from the monitor specifications and perform the division in an application pro- 
gram. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [ 13] Specified view surface not open. 



Inquire Output Function Set Cerror inquire_output_function_set (level, support) 

Cint level; /* level of output */ 

Csuptype * support; /* amount of support */ 

inquire_output_f unct ion_set ( ) reports the extent to which each level 
of the output portion of the ANSI CGI standard is supported. 

typedef enum { 

NONE, 

REQUIRED_FUNCT IONS_ONLY , 

SOME_NON_REQUIRED_FUNCTIONS , 

ALL_NON_REQUIRED_FUNCT IONS 
} Csuptype; 

The standard requires that the level argument be an enumerated type; however, 
for reasons of simplicity only the level number is used by SunCGI. Levels 1-6 
are supported completely (that is, both required and non-required functions are 
implemented). Level 7 is not supported at all. Refer to the ANSI standard for 
the precise definition of each level. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 



Inquire VDC Type Cerror inquire_vdc_type (type) 

Cvdctype *type; /* type of VDC space */ 

inquir e_vdc_type ( ) reports the type of coordinates used by SunCGI in the 
returned argument type. 

typedef enum { 

INTEGER, 

REAL, 

BOTH 

} Cvdctype ; 

type is always set to INTEGER (32-bit). SunCore is a higher-level graphics sys- 
tem with coordinate space expressed in real numbers. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 
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Inquire Output Capabilities Cerror inquire_output_capabilities (first, num, list) 

Cint first; /* first element */ 

Cint mam; /* number of elements in list to be returned 

Cchar *list[]; /* returned list */ 

inquire_output_capabilities ( ) lists the output functions in the 
returned argument list. The range of the first and mim arguments is determined 
by the returned argument output from the inquire_device_class ( ) func- 
tion. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC 

EINQLTL [16] Inquiry arguments are longer than list. 

Input devices have a separate class of negotiation functions. Input capability 
inquiries report qualitative abilities as well as quantitative abilities of input dev- 
ices. The inquire_input_capabilities ( ) function reports which dev- 
ices and overall features are supported by SunCGI. The remaining functions 
report the capabilities of individual devices or features. Input devices are virtual 
devices which must be associated with physical triggers (such as mouse but- 
tons). Initializing an input device defines the measure used by a device, for 
example initializing a LOCATOR device defines the measure as x-y coordinates. 
In addition to being associated with a trigger, each device has selectable screen 
echoing capabilities. Association and echoing capabilities for each input device 
are reported by the functions described in this section. 

Inquire Input Capabilities Cerror inquire_input_capabilities (valid, table) 

Clogical *valid; /* device state */ 

Ccgidesctab *table; /* CGI input description table */ 

inquire_input_capabilit ies ( ) reports the total number of input dev- 
ices of each class that is supported. The argument valid returns the value 
L_TRUE if SunCGI is initialized, and L_FALSE otherwise. If valid is set to 
L_TRUE, the elements of table are set to the quantity and quality of inputs sup- 
ported. All Sun Workstations support input at the same level. 



2.5. Input Capability 
Inquiries 
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Inquire LID Capabilities 



typedef struct { 

Cint numloc; 

Cint nuinval; 

Cint numstrk; 

Cint numchoice; 

Cint numstr; 

Cint nvimtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_map; 

Csuptype echo; 

Csuptype tracking; 

Csuptype prompt; 

Csuptype acknowledgement; 

Csuptype trigger_manipulation; 

} Ccgidesctab; 

Elements of type Cint report how many of each type device is supported, as 
well as how many types of triggers are supported. Elements of type Csuptype 
report how many of the functions of each class are supported. AH functions 
except the tracking functions are fuUy supported. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 



Cerror inquire_lid_capabilities (devclass, devnum, 
valid, table) 

Cdevoff devclass; 

Cint devniim; /* device number */ 

Clogical *valid; /* device supported at all */ 

Cliddescript *table; /* table of descriptors */ 

inquire_lid_capabilities ( ) describes the capabilities of a specific 
input device (hereafter, specified device). The input arguments devclass and dev- 
num refer to a specific device type and number. The argument valid reports 
whether CGI is initialized. 

typedef struct { 

Clogical sample; 

Cchangetype change; 

Cint numassoc; 

Cint *trigassoc; 

Cinputability prompt; 

Cinputability acknowledgement; 

Cechotypelst *echo; 

Cchar *classdep; 

Cstatelist state; 

} Cliddescript; 

Cliddescript indicates whether an ability is present in the specified logical 
input device. The change element reports whether associations are changeable at 
all (all input devices except string are changeable). The numassoc and trigassoc 
elements of table report how many and which triggers may be associated with the 
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Specified logical input device. SunCGI does not support either prompt or ack- 
nowledgement for any input device. The echo argument describes which echo 
types are supported (see Chapter 5 for a list of echo types). ^ The classdep argu- 
ment provides class dependent information in character form (the type of infor- 
mation is given in Table 2-5). If more than one piece of class dependent infor- 
mation is returned, then the pieces of information are separated by commas. The 
state argument reports the initial state of the specified device. See the 
inquire_lid_state_list 0 function. 

Table 2-5 Class Dependent Information 



Device Class 


Information 


Possible Values 


IC_LOCATOR 


Coordinate Mapping 


Yes, No, Partial 




Native Range 


xmin, xmax. 






ymin, ymax 


IC_VALUATOR 


Set Valuator Range 


yes/no 


IC_STROKE 


Time Increment Settable 


yes/no 




Minimum Distance 


yes/no 


IC_CHOICE 


Range 


min/max 


IC_STRING 


None 


None 



ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC 



Inquire Trigger Capabilities Cerror inquire_trigger_capabilities (trigger, valid, tdis) 

Cint trigger; /* trigger number */ 

Clogical *valid; /* trigger supported at all */ 

Ctrigdis *tdis; /* trigger description table */ 

inquire_trigger_capabilities ( ) describes how a particular trigger 
can be associated. The argument valid reports whether the device supports input 
at all. 

typedef struct { 

Cchangetype change; 

Cassoclid *numassoc; 

Cint maxassoc; 

Cpromstate prompt; 

Cackstate acknowledgement; 

Cchar *name; 

Cchar *description; 

} Ctrigdis; 

The change element of tdis reports whether the specified trigger can be associ- 
ated with a logical input device. The numassoc element of tdis gives supported 
LID associations for this trigger. This consists of n, the number of LID classes 
which can be associated with the trigger, a pointer to an array of n entries teUing 
which n device classes can be associated with the trigger, and how many of each 

^ Note that inquire_lid_capabilities ( ) returns an enumerated type whereas trackon () 
accepts integers. Therefore these values may be different 
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device class is defined. The maxassoc field gives the number of LIDs which can 
be concurrently associated with this trigger. SunCGI does not support either 
prompt or acknowledgement for any input device. The name element is simply a 
character form of the trigger name (for example, LEFT MOUSE BUTTON). The 
description element is never filled and is included for standards compatibility. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 


EINTRNEX [86] 


Trigger does not exist. 
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3 

Output 



SunCGI supports two classes of output primitives: geometrical output primitives 
and raster primitives. 

Geometrical Output Primitives 

include arcs, circles, polylines, polygons, and markers. The position of 
geometrical output primitives are always specified in absolute VDC coordi- 
nates.^ 

Raster Primitives 

draw text and scaled and unsealed 2D arrays. The coordinate system for ras- 
ter primitives depends on the type of primitive. The drawing mode deter- 
mines how output primitives are drawn on top of other output primitives or 
the background. 

3.1. Geometrical Output Geometrical primitives (except polymarker ( ) ) are considered either closed 
Primitives or not closed. Polymarker uses its own attributes (see Section 4.3). Non-closed 

figures (polylines, circular arcs, or elliptical arcs) are drawn with a style, width 
and color determined from line attributes (see Section 4.2). Qosed figures 
(polygons, rectangles, circles, ellipses, and circular and elliptical closed arcs) use 
the solid object attributes (see Section 4.4). The geometrical information 
specifies the boundary of a closed figure. The interior of this boundary is filled 
using fill area attributes. The boundary may be surrounded with a line, drawn 
with perimeter attributes, not the line attributes. For example, a circle of radius 
1000 and a perimeter width of 100 VDC units has its perimeter between the circle 
of radius 1000 and a concentric circle of radius 1100 (not from 950 through 
1050). 



SunCGI (unlike SunCore) maintains no concept of current position. 
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Most polygonal primitives (polyline ( ) , polymarker ( ) , polygon ( ) , 
and partial_polygon ( ) ) take one argument of type Ccoorlist : 

typedef struct { 

Cint x; 

Cint y; 

} Ccoor; 

typedef struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoorlist; 

The element ptlist is really a pointer to an array of type Ccoor, which contains 
the n coordinates of the points defining the primitive. The style, color, and other 
features of lines, maikers, and fill patterns used by geometrical output primitives 
are set by the attribute functions described in Chapter 4. 

The polygons generated by SunCGI may or may not be closed. SunCGI automat- 
ically assumes the polygon is closed for the purpose of filling. However, a 
polygon must be explicitly closed in order to get all of its edges drawn, so take 
care to generate explicitly closed polygons. The rectangle ( ) fimction impli- 
citly generates closed objects.^ 

SunCGI has two classes of conical primitives: circular and elliptical. Each class 
has fimctions for drawing solid objects, arcs, and closed arcs. Drawing of conical 
primitives is regulated by the same attributes that regulate the drawing of 
polygons and polylines. 

Polyline Cerror polyline (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polyline ( ) draws lines between the points specified by the ptlist element of 
polycoors. polyline ( ) does not draw a line between the first and last element 
of die point list. To generate a closed polyline, the last point on the list must 
have the same coordinates as the first point on the list. The style, color, and 
width of the lines are set by the polyline_bundle_index ( ) , 
line_type ( ) , line_color ( ) , line_width ( ) and 
line_width_specification_mode ( ) fimctions. If a line segment of a 
polyline has a length of zero, the line is not drawn. To draw a point, use the 
circle ( ) function. If you specify a polyline that has less than two points, an 
error is generated. Similarly, if the number of points specified is greater than the 
maximum number of points (MAXPTS), an error is generated. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

ENMPTSTL [60] Number of points is too large. 

EP LMT WP T [6 1 ] Polylines must have at least two points. 



A closed portion of a closed figure boundaiy will not be drawn if it exceeds a clipping boundary. 
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Disjoint Polyline 



Polymarker 



Polygon 



Cerror dis joint_jpolyline (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

dis joint_poly line ( ) draws lines between pairs of elements in ptlist. The 
line attributes described in Section 4.2 determine the appearance of the 
dis joint_polyline ( ) function. If polycoors contains an odd number of 
points, the last point is ignored. As with polyline ( ) , if the number of points 
is less than two or greater than MAXPTS, an error is generated. 

dis joint_polyline ( ) is typically used to implement scan-line polygon 
filling algorithms. 

ENOTVSAC [4] CGI not in proper state; CGI shall be in state VSAC. 
ENMPTSTL [60] Number of points is too large. 

EPLMTWPT [61] Polylines must have at least two points. 

Cerror polymarker (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polymarker ( ) draws a marker at each point. The type, color, and size of 
marker are set by the polymarker_bundle_index ( ) , marker_type ( ) , 
marker_color { ) , marker_size ( ) , and 

marker_size_specif ication_mode ( ) functions. If the number of 
points specified is greater than the maximum number of points, an error is gen- 
erated. polymarker 0 is useful for making graphs such as scatter plots. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

ENMPTSTL [60] Number of points is too large. 

Cerror polygon (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polygon 0 displays the polygon described by the points in /76>/ycoor5. Any 
points added to the global polygon list by the partial_polygon ( ) function 
are also displayed. The polygon is filled between edges. Polygons are allowed 
to be self-intersecting. The visibility of individual edges can only be set by the 
part ial_polygon ( ) function. The style and color used to fiU the polygon 
are set by the solid object attribute functions described in Chapter 4. The charac- 
teristics of the edges are controlled by the perimeter attribute functions. The 
number of points in the polygon used to determine the error condition of too few^ 
or too many points is the total number of points on the global polygon list, not 
the number of points specified in polycoors. After the polygon is drawn, the glo- 
bal polygon list is emptied. 



® The CGI standard specifies that polygon ( ) may be called with fewer than three points without 
generating an error. Zero points should be a no-op, one should be a point, and two should be a line segment. 
SunCGI does not support these degenerate polygons. 
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KNOT vs AC [4] CGI not in proper state: CGI shall be in state VS AC. 

ENMP TS TL [60] Number of points is too large. 

EPGMTHPT [62] Polygons must have at least three points. 

EGP L I S FL [63] Global polygon list is full. 

Partial Polygon Cerror partial_polygon (polycoors, cflag) 

Ccoorlist *polycoors; /* list of points */ 

Ccflag cflag; /* CLOSE previous polygon? */ 

partial_polygon { ) adds elements to the global polygon list without 
displaying the polygon. The partial_polygon ( ) function provides the 
capability of drawing multiple-boundary polygons, including polygons with 
holes. The drawing is actually performed when polygon { ) is called, 
polygon ( ) will close the last boundary on the global polygon list and add the 
coordinate list it is passed as the final polygon boundary before drawing. 

cflag controls whether the last polygon in the global polygon list is open or 
closed. If cflag is set to CLOSE, the last polygon on the global polygon list will 
be closed by drawing a visible perimeter edge between the last and the first points 
of the last polygon on the global polygon list. If the cflag is set to OPEN, the 
points in polycoors are appended to the last polygon on the global polygon list, 
but an invisible perimeter edge will be drawn between the last point currently on 
the global polygon list and the first point in the Ccoorlist. The visibihty of 
polygon edges can be individually controlled by calling 

partial_polygon ( ) with cflag set to OPEN for each invisible edge and with 
cflag set to CLOSE for each new boundary. The interpretation of cflag is slightly 
different than the pseudocode given in the CGI standard. Future versions of CGI 
may use a different syntax to offer the capabilities of multiple-boundary 
polygons and invisible edges. 

The CGI standard specifies that circle ( ) , rectangle ( ) and ellipse ( ) 
are primitives that may use the globed polygon list for filling. SunCGI does not 
use the global polygon list in these functions, and therefore leaves it untouched. 
These SunCGI routines do not empty the global polygon list. 

An error is detected if the number of points on the global polygon list exceeds 
MAXPTS. In this case, the polygon on the global polygon list is drawn, and the 
new information is not added. The same error handling applies to polygon ( ) . 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

ENMPTSTL [60] Number of points is too large. 

EPGMTHPT [62] Polygons must have at least three points. 

EGPLISFL [63] Global polygon list is full. 
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tinclude <cgidefs.h> 



tdefine NPTS 



Cvwsurf device; 

Ccoor list [NPTS]; 

Ccoorlist points; 



/* list of coords. */ 

/* structure for list of coords. */ 



NORMAL VWSURF (device, PIXWINDD) ; 



open_cgi ( ) ; 

open_vws ( &name, Sdevice) ; 
interior_style (SOLIDI, ON); 



list [0] .X 
list [1] .X 
list [1] . y 
list [2] .X 
list [3] . X 
list [3] .y 



list [0] .y = 10000; 
10000 ; 

20000 ; 

list[2].y = 20000; 



list [0] .X 
list [1] .X 
list [1] .y 
list [2 ] . X 
list [3] .X 
list [3] .y 



list [0] .y 

12500; 

17500; 

list [2] .y 

17500; 

12500; 



= 12500; 



= 17500; 



points .ptlist = list; 
points.n = NPTS; 
polygon (&points) ; 



/* solid fill with edge */ 



list[3].x = 20000; 
list [3] .y = 10000; 
points .ptlist = list; 
points.n = NPTS; 

partial__polygon (&points, CLOSE); 



/* draw closed polygon */ 



/*[ Redundant , but good practice]*/ 



/* cut a hole in it */ 



sleep (10) ; 

close_vws (name) ; 
close cgi(); 
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Rectangle 



Circle 



Circular Arc Center 



Cerror rectangle (rbc, Itc) 

Ccoor *rbc, *ltc; /* corners defining rectangle */ 

rectangle ( ) displays a box with its lower right-hand comer at point rbc and 
its upper left-hand comer at point Itc. Calls to rectangle ( ) do not affect the 
global polygon list. The interior of the rectangle (the filled portion) is defined by 
rbc and Itc. The perimeter is drawn outside of this region. The appearance of the 
rectangle is determined by the fill area and perimeter attributes. A rectangle with 
one side coincident with a clipping boundary specifies an interior extending to 
the boundary. Hence, a portion of the perimeter is outside the clipping boundary 
and is not drawn. 

If the arguments to rectangle ( ) would result in a point or a line, the point or 
line is drawa However, if the arguments to rectangle determine a point, the 
point is drawn with width zero, regardless of the current value of perimeter 
width. If the values of rbc and Itc are reversed, the points are automatically 
reversed and the rectangle is drawn normally. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror circle (cl, rad) 

Ccoor *cl; /* center */ 

Cint rad; /* radius */ 

circle ( ) draws a circle of radius rad centered at cl. The argument rad is 
expressed in terms of VDC space. The color, form, and visibility of the interior 
and perimeter are controlled by the same solid object attributes which control the 
drawing of polygons and rectangles. 

The argument rad determines the size of the interior of the circle. Therefore, a 
circle with a thick perimeter may be larger than expected. If the radius is zero, a 
point is drawn, and no textured perimeter is drawn, even if the perimeter width is 
large. If the radius is negative, the absolute value of the radius is used. 

Textured circles may possibly contain an incorrect element at one point because 
the digital circumference may not be exactly divisible by the length of the texture 
element, 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror circular_arc_center (cl, c2x, c2y, c3x, c3y, rad) 

Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; /* endpoints */ 

Cint rad; /* radius */ 

circular_arc_center ( ) draws a circular arc between points c2x, c2y and 
c3x, c3y with circle of radius rad at center cl. Point c2x, c2y is the starting point 
and point c3x, c3y is the ending point. Circular arcs are drawn in a counterclock- 
wise manner. 

If rad is negative, the points 180 degrees opposite fiom c2x, c2y and c3x, c3y are 
used as the endpoints of the arc. If the rad is zero, a point is drawn at cl. If 
either c2x, c2y or c3x, c3y are not on the circumference of the circle determined 
by cl and rad, an error is generated, and the arc is not drawn. The attributes 
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which determine the style, width, and color of the arc are the same functions 
which regulate the drawing of polylines. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EARCPNCI [64] Arc points do not lie on circle. 

Circular Arc Center Close Cerror circular_arc_center_close (cl, c2x, 

c2y, c3x, c3y, rad, close) 

Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; /* endpoints */ 

Cint rad; /* radius */ 

Cclosetype close; /* PIE or CHORD */ 

circular_arc_center_close ( ) draws a closed arc centered at cl with 
radius rad and endpoints c2x, c2y and c3x, c3y. Arcs are closed with either the 
PIE or CHORD algorithm. The PIE algorithm draws a line from each of the end- 
points of the arc to the center point of the circle. SunCGI then fiUs this region as 
it would any other solid object. The CHORD algorithm draws a line connecting 
the endpoints of the arc and then fills this region using solid object attributes. 
circular_ar c_center_close ( ) is useful for drawing pie charts (see the 
following example program). 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EARCPNCI [64] Arc points do not lie on circle. 



tinclude <cgidefs.h> 

/* Indices of colors to be used. Using the defaults. */ 

tdefine RED 1 

#define YELLOW 2 

tdefine GREEN 3 

#define CYAN 4 

/* definitions for circle coord's and values */ 
tdefine MID 16000 

tdefine RAD (MID / 2) 

tdefine MIN (MID - RAD) 

#define MAX (MID + RAD) 

mainO /* draws four quadrants in different colors and fills */ 

{ 

Ccoor cl; /* coord of center */ 

Cint name; /* CGI name for view surface */ 

Cvwsurf device; /* view surface device struct */ 

cl.x = cl.y = MID; /* center */ 

NORMAL_VWSURF ( device, CGPIXWINDD) ; 

open_cgi ( ) ; 

open_vws ( &name, & device) ; 

^ 
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perimeter_width ( 1.0); 



/* perimeter width 1% of VDC */ 



interior_style ( SOLIDI, OFF) ; 

fill_color( RED); /* color of quadrant 1 */ 

circular_arc_center_close ( &cl, MAX, MID, MID, MAX, RAD, PIE) ; 

interior_style ( HOLLOW, OFF); 

fill_color( YELLOW); /* color of quadrant 2 */ 

circular_arc_center_close ( &cl, MID, MAX, MIN, MID, RAD, PIE); 

interior_style ( SOLIDI, ON); 

fill_color( GREEN); /* color of quadrant 3 */ 

circular_arc_center_close ( &cl, MIN, MID, MID, MIN, RAD, PIE) ; 

interior_style ( HOLLOW, ON) ; 

fill_color{ CYAN); /* color of quadrant 4 */ 

circular_arc_center_close ( &cl, MID, MIN, MAX, MID, RAD, PIE) ; 

sleep (10) ; 

close_vws (name) ; /* close view surface and CGI */ 

close_cgi () ; 



Circular Arc 3pt Cerror circular_arc_3pt (cl, c2, c3) 

Ccoor *cl, *c2, *c3; /* starting, intermediate 

and ending points */ 

circular_ar c_3pt ( ) draws a circular arc starting at point cl and ending at 
point c3 which is guaranteed to pass through point c2. The line attributes func- 
tions described in Section 4.2 determine the appearance of the 
cir cular_arc_3pt ( ) function. If the circular arc is textured (for example, 
dotted) then the intermediate point may not be displayed. However, if the arc is 
solid, the intermediate point is always drawn. If the three points are colinear, a 
line is drawa If two of the three points are coincident, a line is drawn between 
the two distinct points. Finally, if aU three points are coincident, a point is 
drawn. circular_arc_3pt ( ) is considerably slower than 
circular_arc_center ( ) ; therefore, you are advised to use 
cir cular_ar c_center ( ) if both functions can meet your needs. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

Circular Arc 3pt Close Cerror circular_arc_3pt_close (cl, c2, c3, close) 

Ccoor *cl, *c2, *c3; /* starting, intermediate 

and dnding points */ 

Cclosetype close; /* PIE or CHORD */ 

cir cular_ar c_3pt_close ( ) draws a circular arc starting at point cl and 
ending at point c3 which is guaranteed to pass through point c2. The solid object 
attributes described in Section 4.4 determine the appearance of the 
cir cular_arc_3pt_c lose ( ) function. 
circular_arc_3pt_close ( ) is considerably slower than 
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Ellipse 



Elliptical Arc 



Elliptical Arc Close 



circular_arc_center_close ( ) ; therefore, you are advised to use 
circular_arc_center_close ( ) if both functions meet your needs. 

If the three points are colinear, a line is drawn. If two of the three points are 
coincident, a line is drawn between the two distinct points. Finally, if all three 
points are coincident, a point is drawn. In none of these cases wiU any region be 
filled. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror ellipse (cl, majx, miny) 

Ccoor *cl; /* center */ 

Cint majx, miny; /* length of x and y axes */ 

ellipse draws an ellipse centered at point cl with major (x) and minor (y) axes of 
length majx and miny? If either majx or miny are zero, a line is drawn. If both 
majx and miny are zero, a point is drawn. The attributes which control the draw- 
ing of ellipses are the solid object attributes described in Section 4.4. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror elliptical_arc (cl, sx, sy, ex, ey, majx, miny) 

Ccoor *cl; /* center */ 

Cint sx, sy; /* starting point of arc */ 

Cint ex, ey; /* ending point of arc */ 

Cint majx, miny; /* endpoints of major and minor axes */ 

elliptical_arc ( ) draws an elliptical arc centered at cl with major {x) and 
minor (y) axes of length majx and miny. sx, sy and ex, ey are the starting and 
ending points of the arc. An error is generated (and the ellipse is not drawn) if 
the points {sx, sy, and ex, ey) are not on the perimeter of the ellipse. Elliptical 
arcs are drawn in a counterclockwise manner. Switching the values of sx, sy and 
ex, ey will produce complementary arcs. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a 
point is drawn. Polyline attributes are used to determine the appearance of ellipt- 
ical arcs. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

EARCPNEL [65] Arc points do not lie on ellipse. 

Cerror elliptical_arc_close (cl, sx, sy, ex, 
ey, majx, miny, close) 

Ccoor *cl; /* center */ 

Cint sx, sy; /* starting point of arc */ 

Cint ex, ey; /* ending point of arc */ 

Cint majx, miny; /* endpoints of major and minor axes */ 
Cclosetype close; /* PIE or CHORD */ 



® Although the axes are called the major and minor axes by the standard they are really the x and y axes. In 
fact, the X axis can either be the major or minor axis, depending on the relative length of the y axis. 
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3.2. Raster Primitives 



Text 



VDM Text 



elliptical_arc_close ( ) draws an elliptical arc specified by sx, sy, ex, ey 
and majx, miny. The arc is closed with either the PIE or CHORD algorithm. The 
same restrictions on sx, sy, ex, and ey are applied to 
elliptical_arc_close { ) as to elliptical_arc ( ) . However, 
elliptical_arc_close ( ) uses the fill area and perimeter attributes, 
whereas elliptical_arc ( ) uses the line attributes. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a 
point is drawn. In neither of these cases will any region be filled. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EARCPNEL [65] Arc points do not lie on ellipse. 

Raster primitives include text, cell arrays, pixel arrays, and bitblts (bit block 
transfer). Bitblts are pixel arrays (bitmaps) which can be drawn using the various 
drawing modes. The current drawing mode determines how bitblt primitives are 
affected by information which is already on the screen. Raster primitives differ 
from geometrical primitives because their dimensions are not necessarily 
expressed in VDC space. Therefore, you must be careful to consider whether 
position arguments are expressed in VDC space or screen coordinates. 

Cerror text (cl, tstring) 

Ccoor *cl; /* starting point of text (in VDC space) */ 

Cchar *tstring; /* text */ 

text ( ) displays the text contained in tstring at point cl (expressed in VDC 
space). The appearance of text is controlled by the text attributes described in 
Section 4.8. (Control characters are displayed as blanks, except in the SYMBOL 
font where they may be drawn as pictures of bugs. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror vc3in_text (cl, flag, tstring) 

Ccoor *cl; /* starting point of text (in VDC space) */ 

Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

vdm_text ( ) displays the text contained in tstring at point cl (expressed in 
VDC space). The intended difference between text ( ) and vdm_text ( ) is 
that vdm_text ( ) allows control characters; however, SunCGI does not handle 
control characters so text drawn with vdin_text ( ) wUl appear identical to text 
drawn with the text ( ) function. If the jlag argument is equal to FINAL, the 
previous text and the appended text are aligned separately. However, if the/ag 
argument is equal to NOT_FINAL, the appended and previous text are aligned 
together. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 
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Append Text 



Inquire Text Extent 



Cerror append_text (flag, tstring) 

Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

append_text { ) displays the text contained in tstring after the end of the most 
recently written text. The type of text written depends on the same attributes 
which control the display of text. The flag argument determines whether the 
appended text is aligned with the previous text if the alignment is continuous. If 
the flag argument is equal to FINAL, then the previous text and the appended text 
are aligned separately. However, if the flag argument is equal to NOT_FINAL, 
the appended and previous text are aligned together. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror inquire_text_extent (tstring, nextchar, concat, 
lleft, uleft, uright) 

Cchar *tstring; /* text */ 

Cchar nextchar; /* next character (for kerning) */ 

Ccoor *concat; /* concatenation point */ 

Ccoor *lleft, *uleft, *uright; 

/* coordinates of text bounding box */ 

inquire_text_extent ( ) determines how large text tstring would be and 
where it would be placed if it were drawn using the current text attributes. The 
nextchar parameter is used to determine the point where text would start if more 
text (starting with nextchar) were appended to the text specified by tstring}^ If 
nextchar equals 'single space', the last point of the current character is used. The 
argument concat returns the coordinates of the point where appended text would 
start. The arguments lleft, uleft, and uright return three of the four comers of the 
bounding box of text contained in tstring. 

The bounding box is a parallelogram (a rectangle if the character up vector and 
the character base vector are orthogonal). The names of the parallelogram 
comers are correct if no rotation is applied to the text. For some character orien- 
tations, the implied relationships do not hold. For example, lleft may not be the 
lowest. The fourth comer may be easily calculated from the three returned: 

uright->x + lleft->x - uleft->x 
uright->y + lleft->y - uleft->y 

The concatenation point and text alignment parallelogram are returned in VDC 
space, but assume a text position of (0, 0). If the text is to be drawn at a position 
(x, y) then (x, y) must be added to each point to yield the tme locations. 

The values of lleft, uleft, and uright are defined by the bounding box of the char- 
acter and therefore may not be at the exact pixel where the character ends or 
begins. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 



This is a method for accounting for proportional spacing. 
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Cell Array Cerror cell_array (p, q, r, dx, dy, colorind) 

Ccoor *p, *q, *r; 

/* corners of parallelogram (in VDC space) * 
Cint dx, dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

cell_array ( ) draws a scaled and skewed pixel array on the view surface(s). 
Points p, q and r (expressed in VDC space) define a parallelogram. Line p-q is a 
diagonal, p is the comer where the first color is deposited, going in the direction 
of r and continuing filling lines until q. r is one of the remaining two comers, dx 
and dy define the width and the height of the array colorindy which is mapped 
onto the parallelogram defined by p, q, and r. 

cell_array { ) is one of the few primitives which depends on the actual size 
of the view surface. Cell arrays are not drawn if the elements of the array would 
be smaller than one pixel. However, because different view surfaces may have 
different dimensions, a cell array might be drawn on one view surface, but not on 
another smaller view surface. Finally, all cells composing the cell array are the 
same size; therefore, the upper left hand comer of the cell array might be down 
and to the right of point q because of the accumulated error of making aU of the 
cells slightly smaller than their floating point size. For example if each cell of a 
3x3 cell array is supposed to be 3.333 pixels wide, the actual cell array will be 
nine pixels wide instead of ten. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

ECELLATS [66] Distance between p and q too small for given dx, dy. 

ECELLPOS [67] CeU array dimensions must be positive. 

Pixel Array Cerror pixel_array (pcell, m, n, colorind) 

Ccoor *pcell; /* base of array in VDC space */ 

Cint m, n; /* dimensions of color array in screen space 

Cint *colorind; /* array of color values */ 

pixel_array { ) draws the array of colors colorind starting at point pcell 
(expressed in VDC space), m and n (expressed in screen space) define the x and y 
dimensions of the array. Therefore, arrays always have a constant physical 
size, independent of the dimensions of VDC space. The pixel array is drawn 
down and to the right from point pcell. If either m or n are not positive, the abso- 
lute value of m and the absolute value of n are used. pixel_array ( ) is not 
affected by the current drawing mode. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EVALOVWS [69] Value outside of view surface. 
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Bitblt Source Array 



Bitblt Pattern Array 



Cerror bitblt_source_array (pixsource, xo, yo, xe, ye, 
pixtarget, xt, yt, name) 

Cpixrect *pixsource, *pixtarget; 

/* source and target pixel arrays */ 

Cint xo, yo; 

/* coordinates of source array (in VDC space) */ 

Cint xe, ye; 

/* dimensions of source array (in screen space) */ 

Cint xt , yt ; 

/* coordinates of target pixel array (in VDC space) */ 
Cint name; /* view surface name */ 

bitblt_sour ce_array ( ) moves a pixel array from point (xo, yo) to point 
(xt, yt) using the current drawing mode. Both of these points are expressed in 
VDC space. The size of the pixel array is determined by the xe and ye arguments, 
which are expressed in screen space, pixsource and pixtarget are pointers to pix- 
rects, which must already be created by mem_create ( ) These pixrects must 
be the same depth as the view surface: 1-bit deep on a monochrome device, 8- 
bits on a color device. 

The source area of the view surface associated with name is saved into pixsource 
(at 0,0). The target area, after pixsource is applied to it, is read into pixtarget 
pixrect (at 0,0). 

An error is detected if either xe or ye are not positive. If the replicated pattern 
array overlaps with the source array on the screen, the visual result depends on 
the current drawing mode, pixsource and pixtarget may have different contents, 
depending on the screen drawing mode (see the set_drawing_mode ( ) func- 
tion). 

Multiple view surfaces and bitblts are incompatible, so a name argument must be 
specified. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EVALOVWS [69] Value outside of view surface. 



Cerror bitblt_pattern_array (pixpat , px, py, pixtarget, 
rx, ry, ox, oy, dx, dy, name) 



Cpixrect *pixpat; 
Cint px, py; 

Cpixrect *pixtarget; 
Cint rx, ry; 

Cint ox, oy; 

Cint dx, dy; 

Cint name ; 



/* pattern source array */ 

/* pattern extent */ 

/* destination pattern array */ 
/* pattern reference point */ 

/* destination origin */ 

/* destination extent */ 

/* view surface name */ 



bitblt_j)attern_array ( ) replicates the pattern (using the current draw- 
ing mode) stored in pixpat to fill the area of the view surface, which is deter- 
mined by ox, oy and dx, dy. The pattern reference point determines the offset of 



Refer to the Pixrect Reference Manual for more information about pixrects. 
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the pattern array from the point zero. The resultant pattern array is displayed at 
ox, oy. The visual result depends on the current drawing mode. 

pixpat is a pointer to a pixrect which must be created and initialized with the pat- 
tern by the application program, pixtarget is a pointer to a pixrect (with same 
depth as the device) which must already be created by the user, using 
mem_cr eate ( ) . The target area, after pixpat is applied to it, is read into the 
pixtarget pixrect (at 0,0). 

Multiple view surfaces and bitblts are incompatible, so a name argument must be 
specified. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EVALOVWS [69] Value outside of view surface. 

EP XNOT CR [70] Pixrect not created. 

Bitblt Patterned Source Array Cerror bitblt_patterned_source_array (pixpat, px, py, 

pixsource, sx, sy, pixtarget, rx, ry, ox, oy, 
dx, dy, name) 

Cpixrect *pixpat; /* pattern source array */ 

Cint px, py; /* pattern extent */ 

Cpixrect *pixsource; /* source array */ 

Cint sx, sy; /* source origin */ 

Cpixrect *pixtarget; /* destination pattern array */ 

Cint rx, ry; /* pattern reference point */ 

Cint ox, oy; /* destination origin */ 

Cint dx, dy; /* destination extent */ 

Cint name; /* view surface name */ 

bitblt_patterned_source_array ( ) replicates (using the cunent draw- 
ing mode) the pattern stored in pixpat to fill the area of the view surface deter- 
mined by ox, oy and dx, dy. The source area of the view surface is read into the 
pixrect pointed to by pixsource (which must already be created by the user with 
same depth as the device) at 0,0. The source area is stenciled through the repli- 
cated pattern onto the view surface at ox, oy, using the current drawing mode. 

The target area, after the copy, is read into the pixtarget pixrect. If the replicated 
pattern array overlaps with the source array on the screen, the visual result 
depends on the current drawing mode. 

Multiple view surfaces and bitblts are incompatible, so a name argument must be 
specified. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EVALOVWS [69] Value outside of view surface. 

EPXNOTCR [70] Pixrect not created. 
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Inquire Cell Array 



Inquire Pixel Array 



Cerror inquire_cell_ar ray (name, p, q, r, dx, dy, colorind) 
Cint name; /* view surface name */ 

Ccoor *p, *q, *r; 

/* corners of parallelogram (in VDC space) */ 

Cint dx, dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

Points p, q and r (in VDC space) define a parallelogram with line p-q as the diag- 
onal, where p is the lower left-hand comer, r is one of the remaining two 
comers, dx and dy define the width and the height of the array colorind which 
contains the colors of the pixels on the screen which lie within the parallelogram 
defined by p, and r. Notice that a view surface identifier, name, must be 
specified because the result of this function is highly dependent on the dimen- 
sions and contents of the view surface. 



The area of the screen corresponding to the parallelogram is assumed to contain a 
regular grid of points. However, if each element of the grid is larger than one 
pixel, the color of the pixel at the lower left-hand comer of each element of the 
grid is defined to be the color of the grid element. Therefore, the values con- 
tained in colorind are highly dependent on the size of the view surface. An error 
is produced if the elements of the grid are smaller than one pixel. 



ENOTVSAC [4] 
EVSIDINV [10] 
EVSNOTOP [13] 
EVSNTACT [15] 
ECELLATS [66] 
ECELLPOS [67] 



CGI not in proper state: CGI shall be in state VSAC. 
Specified view surface name is invalid. 

Specified view surface not open. 

Specified view surface is not active. 

Distance between p and q too small for given dx, dy. 
Cell array dimensions must be positive. 



Cerror inquire_pixel_array (p, m, n, colorind, name) 

Ccoor *p; /* base of array in VDC space */ 

Cint m, n; /* dimensions of color array in screen space */ 

Cint *colorind; /* array of color values */ 

Cint name; /* view surface name */ 

inquire_pixel_array ( ) fiUs array colorind with the values of pixels in 
the area of the screen defined by point p (expressed in VDC space) and points m 
and n (expressed in screen space). The array is fiUed down and to the right from 
point p. If either m orn are not positive, the absolute value of these arguments is 
used. 

Multiple view surfaces and bitblts are incompatible, so a name argument must be 
specified. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EVALOVWS [69] Value outside of view surface. 

EPXNOTCR [70] Pixrect not created. 
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Inquire Device Bitmap Cpixrect *inquire_device_bitmap(name) 

Cint name; /* name assigned to cgi view surface */ 

inquire_device_bitmap ( ) returns the pixrect that corresponds to the 
view surface. The pixrect describes the entire device, even if the view surface is 
a smaller pixwin. If you want to use subareas of this pixrect or manipulate it any 
other way, refer to the Pixrect Reference Manual. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Inquire Bitblt Alignments Cerror inquire_bitblt_alignments (base, width, px, py, 

maxpx, maxpy, name) 

Cint *base; /* bitmap base alignment */ 

Cint *width; /* width alignment */ 

Cint *px, *py; /* pattern extent alignment */ 

Cint *maxpx, *maxpy; /* maximum pattern size */ 

Cint name; /* name assigned to cgi view surface */ 

inquire_bitblt_alignments ( ) reports the alignment criteria necessary 
for some implementations. These factors are not critical for SunCGI. However, 
you should keep in mind the appropriate depth for the pixrect when talking to a 
specific device. Therefore the arguments base, width, px, and py are always set 
to zero. The arguments maxpx and maxpy are device dependent and determine 
the maximum size of a pattern for bitblt_pattern_array ( ) and 
bitblt_patterned_source_array ( ) . 

Multiple view surfaces and bitblts are incompatible, so a name argument must be 
specified. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 

EVS IDINV [ 10] Specified view surface name is invalid. 

EVSNOTOP [ 13] Specified view surface not open. 

EVSNTACT [15] specified view surface is not active. 

3.3. Drawing Modes Drawing modes determine the result of drawing any output primitive on the clear 

screen (background) or on top of a previously drawn object. Drawing modes 
only affect the drawing of bitblt primitives. However, a non-standard 
set_global_drawing_mode ( ) function is provided, which affects all out- 
put primitives except bitblts. Resetting the drawing mode in the middle of an 
application program only affects those output primitives drawn after the mode is 
reset. The novice user is advised not to reset the drawing mode until the user has 
written at least one application program using SunCGI. 
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Set Drawing Mode Cerror set_drawing_mode (visibility, source, 

destination, combination) 

Cbmode visibility; /* transparent or opaque */ 

Cbitmaptype source; /* NOT source bits */ 

Cbitmaptype destination; /* NOT destination bits */ 
Ccombtype combination; /* combination rules */ 

set_drawing_mode ( ) determines the current drawing mode which in turn 
determines how bitblt primitives are displayed. The visibility argument deter- 
mines how pixels with index zero are treated. 

typedef enum { 

TRANSPARENT, 

OPAQUE 
} Cbmode ; 

typedef enum { 

BITTRUE, 

BITNOT 

} Cbitmaptype; 

typedef enum { 

REPLACE, 

AND, 

OR, 

NOT, 

XOR 

} Ccombtype ; 

If visibility is set to TRANSPARENT, all source pixels with index zero leaye the 
destination pixel unchanged, regardless of the operation, whereas if visibility is 
set to OPAQUE, all pixels are treated normally. The arguments source and desti- 
nation determine whether the contents of the source and destination pixrects are 
NOT-ted before the bitblt operation is performed. 

The combination argument determines how the source and destination pixrects 
are combined. If combination is equal to REPLACE, the source pixrect (after 
optionally being NOT-ted) replaces the destination pixrect. If combination is 
equal to AND, OR, or XOR, the source pixrect and the destination pixrect are 
combined in the indicated Boolean fashion. If combination is equal to NOT, then 
the destination is set to a bitwise NOT operation of the source pixrect. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 



Set Global Drawing Mode Cerror set_global_drawing_mode (combination) 

(SunCGI Extension) Ccombtype combination; /* combination rules */ 

set_global_drawing_mode ( ) determines the current global drawing 
mode which in turn determines how all output primitives except bitblts are 
displayed. The combination argument determines how the source and destina- 
tion pixrects are combined. If combination is equal to REPLACE (the default 
value), the output primitive replaces the destination background. If combination 

Revision A, of 9 May 1988 






52 SunCGI Reference Manual 



Inquire Drawing Mode 



is equal to AND, OR, or XOR, the output primitive and the information on the 
screen are combined in the indicated Boolean fashion. If combination is equal to 
NOT, then the destination is set to a bitwise NOT operation of the source piKiect. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Cerror inquire_drawing_mode (visibility, source, 
destination, combination) 

Cbmode *visibility; /* transparent or opaque */ 

Cbitmaptype *source; /* NOT source bits */ 

Cbitmaptype *destination; /* NOT destination bits */ 
Ccombtype *combination; /* combination rules */ 

inquir e_drawing_mode ( ) returns the values of the four components of the 
current drawing mode. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC 
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Attributes 



The current attributes determine how output primitives are displayed. Attributes 
are not specific to any view surface, but affect all view surfaces. The default 
attributes are defined in Table 4-1. 

The attributes associated with an output primitive may be set either individually 
or in bundles. The method for setting the current attribute depends on the state of 
the aspect source flag (ASF) of each attribute. The ASF works as follows: 

□ If the ASF for an attribute is INDIVIDUAL, then the value used is the current 
value set for that individual attribute. For example, a line is drawn in the 
current line color as set by the last call to the line_color ( ) function. 

□ If the ASF is BUNDLED, then the value for that attribute is obtained from the 
entry in the bundle table, as set by the def ine_bundle_index ( ) func- 
tion. The bundle table is a collection of attributes for a particular type of 
primitive. A bundle table may describe the appearance of lines, markers, fill 
areas, edges, and text. 

Each attribute in the bundle table is pointed to by a bundle index. The value 
of a BUNDLED attribute is determined by this index and the contents of the 
specified bundle when the primitive is generated. The default bundle index 
is 1 (which initially contains the default values for the attribute). The max- 
imum value for a bundle index is 10. 

By using a bundle table you can set multiple attributes for an output primi- 
tive with a single function call. For example, a bundle table may be defined 
and then referenced that will set the line type, line width, and fine color for 
subsequent polyline ( ) calls. 

The majority of this chapter is devoted to individual attribute functions. Indivi- 
dual attribute functions are grouped according to the output primitives they 
effect: polylines, polymarkers, fiUed objects, and text. The color_table ( ) 
function (which redefines color lookup table entries) is also included in this 
chapter. Finally, functions for obtaining the values of the current attributes are 
discussed. 
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T able 4-1 Default Attributes 



Attribute 


Value 


Bundle Attributes: 




AUASFs 


INDIVIDUAL 


AU Bundle Indices 


1 


Line Attributes: 




Line Color 


1 


Line Endstyle 


BEST_FIT 


Line Type 


SOLID 


Line Width 


0.0 


Line Width Specification Mode 


SCALED 


Marker Attributes: 




Marker Color 


1 


Marker Size 


4.0 


Marker Size Specification Mode 


SCALED 


Marker Type 


DOT 


Fill Attributes: 




Fill Color 


1 


FiU Hatch Index 


0 


Fill Pattern Index 


1 


Interior Style 


HOLLOW 


Number of Pattern Table Entries 


2 


Pattern Size 


300,300 


Pattern Reference Point 


0,0 


Pattern with Fill Color 


OFF 


Perimeter Color 


1 


Perimeter Type 


SOLID 


Perimeter Visibility 


ON 


Perimeter Width 


0.0 


Perimeter Width Specification Mode 


SCALED 


Text Attributes: 




Character Base jc 


1.0 


Character Base.y 


0.0 


Character Expansion Factor 


1.0 


Character Height 


1000 


Character Path 


RIGHT 


Character Spacing 


0.1 


Character Up jc 


0.0 


Character Up.y 


1.0 


Fixed Font 


0 


Fontset 


1 


Horizontal Text Alignment 


NRMAL 


Text Color 


1 


Text Continuous Alignment.^ 


1.0 
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T able 4-1 Default Attributes — Continued 



Attribute 


Value 


Text Continuous Alignmenty 


1.0 


Text Font 


STICK 


Text Precision 


STRING 


Vertical Text Alignment 


NORMAL 



The attribute selector fimctions determine whether the current attributes are 
defined individually or by using a bundle table. The CGI standard specifies the 
bundle table as read-only but SunCGI allows user-definition of entries in the bun- 
dle table. 

The following example program illustrates how to change the appearance of 
primitives with bundled attributes. The program draws a polyline using different 
line style and line width attributes. The bundled define also shows possible non- 
default attributes for other output primitives. 



4.1. Bundled Attribute 
Functions 



#include <cgidefs.h> 

#define BOXPTS 5 

fdefine NUMATTRS 18 

#define BUNDLE_INDEX 2 

Ccoor box[BOXPTS] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 }; 

Cbunatt bundle = { DASHED_DOTTED, 1., 4, X, 6., 4, 

PATTERN, 1, 1, 2, DOTTED, 1.5, 1, 

STICK, CHARACTER, 1.3, 0.05, 1 }; 

main ( ) 

{ 

Cint i, /* counter variable */ 

name ; 

Cvwsurf device; 

Ccoorlist boxlist; /* structure of coords. */ 

Cflaglist flags; /* structure of ASF's */ 

boxlist. n = BOXPTS; 

boxlist .ptlist = box; 

NORMAL_VWSURF (device, PIXWINDD) ; 

open_cgi ( ) ; 

open_vws (&name, & device) ; 

/* allocate room for array of ASF's (one for each attribute) */ 
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flags. value = (Casptype *) malloc ( NUMATTRS*sizeof (Casptype) ); 
flags. num = (Cint *) malloc ( NUMATTRS*sizeof (Cint ) ); 

/* set all the ASF's to "BUNDLED", and set the appropriate flag #'s */ 
for (i = 0; i < NUMATTRS; i++) { 

f lags . value [i] = BUNDLED; 
flags. num [i] = i; 

} 

flags.n = NUMATTRS; 

/* define our bundle which contains a setting for every attribute */ 
def ine_bundle_index ( BUNDLE_INDEX, Sbundle) ; 
set_aspect_source_f lags ( Sflags) ; 

polyline_bundle_index ( BUNDLE_INDEX) ; /* select our polyline bundle */ 

polyline ( Sboxlist) ; 
sleep (10) ; 

close_vws (name) ; /* close view surface and CGI */ 

close_cgi () ; 

} 

s > 



Set Aspect Source Flags Cerror set_aspect_source_f lags (flags) 

Cflaglist *flags; /* list of ASFs */ 

set_aspect_source_flags () determines whether individual attributes 
are set individually or from bundle table entries. 

typedef struct { 

Cint n; 

Cint num [ ] ; 

Casptype value [ ] ; 

} Cflaglist; 

The n element of the flags argument determines how many flags are to be set. 

The num array of the flags argument determines which flags are to be set. Flag 
numbers are provided in Table 4-2. Finally, the value array of the flags argument 
determines the values of the flags specified in num. If a value is assigned to 
INDIVIDUAL, the individual attribute functions affect the current attribute. If the 
value of index is BUNDLED, calls to individual attribute functions have no 
ejfect.^^ The default value of aU aspect source flags is INDIVIDUAL. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 



In fact, SunCGI currently produces error 30 when these individual attribute fimaion is called while the 
corresponding ASF is BUNDLED. 
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Table 4-2 Attribute Source Flag Numbers 



Flag 


Attribute 


Flag 


Attribute 


0 


line type 


9 


fin color 


1 


line width 


10 


perimeter type 


2 


line color 


11 


perimeter width 


3 


marker type 


12 


perimeter color 


4 


marker width 


13 


text font index 


5 


marker color 


14 


text precision 


6 


interior style 


15 


character expansion factor 


7 


hatch index 


16 


character spacing 


8 


pattern index 


17 


text color 



Define Bundle Index (SunCGI Cerror define_bundle_index (index, entry) 

Extension) Cint index; /* entry in attribute bundle table */ 

Cbunatt *entry; /* new attribute values */ 

def ine_bundle_index ( ) defines an entry in the bundle table. The type 
Cbunatt is a structure that contains elements corresponding to all the attributes. 
index is an entry into a list of available attribute bundles. The default bundle 
index is set to 1 (which initially contains the default value for the attributes 
specified in Table 4-1). The maximum value for a bundle table index is 10, and 
the minimum value is 1. If the contents of a bundle table entry are changed, all 
subsequently drawn primitives use the information in the new entry, depending 
on the relevant aspect source flags. You should keep this fact in mind if you are 
designing display list traversal algorithms using SunCGI. 

typedef struct { 

Clint ype line_type; 

Cfloat line_width; 

Cint line_color; 

Cmartype marker_type; 

Cfloat marker_size; 

Cint marker_color; 

Cintertype interior_style; 

Cint hatch_index; 

Cint pattern_index; 

Cint fill_color; 

Clintype perimeter_type; 

Cfloat perimeter_width; 

Cint perimeter_color / 

Cint text_font; 

Cprectype text_j5recision; 

Cfloat character_expansion; 

Cfloat character_spacing; 

Cint text_color; 

} Cbunatt; 

In addition to the errors listed below, other errors can be detected if any of the 
attribute values are invalid, as specified in later sections. Results are undefined if 
an error occurs. 
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4.2. Line Attributes 



Polyline Bundle Index 



Line Type 



ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBBDTBDI [31] Bundle table index out of range. 

SunCGI provides for specifying the style, width and color of lines which consti- 
tute polylines, circular arcs, and elliptical arcs. The functions do not affect the 
drawing of the perimeter of solid objects, which are set by the perimeter func- 
tions. 



Cerror polyline_bundle_index (index) 

Cint index; /* polyline bundle index */ 

polyline_bundle_index { ) sets the current polyline bundle index to the 
value of index. The contents of the polyline bundle index are line type, line width 
and line color. The line width specification mode and the line endstyle attributes 
are not included in the polyline bundle. If index is not defined, an error is gen- 
erated, and the polyline bundle index does not change. If the ASFs for any of 
these attributes is set to BUNDLED, the current values of these attributes are set 
to the contents of the bundle. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBADLINX [33] Polyline index is invalid. 

Cerror line_type (type) 

Clintype type; /* style of line */ 

line_type ( ) defines the line type for polylines. The enumerated type Clin- 
type contains values that correspond to valid line types. 

typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 

DASH_DOT_DOTTED , 

LONG_D ASHED 
} Clintype; 

The default line style is SOLID. The actual representation of a line on the screen 
is affected by the line endstyle. DASH_DOT_DOTTED actually has three dots 
between dashes. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 
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Line Endstyle (SunCGI 
Extension) 



Line Width Specification 
Mode 



Cerror line_endstyle (type) 

Cendstyle type; /* style of line */ 

line_endstyle ( ) determines how a textured (non-SOLID) line terminates. 
The enumerated type Cendstyle contains values that correspond to valid line 
end styles. 

typedef enum { 

NATURAL, 

POINT, 

BEST_FIT 
} Cendstyle; 

If the endstyle selected is NATURAL, the last component of the line texture (for 
example, a dash or a dot) which can be completely drawn is drawn. A blank 
space at the end of the line may cause the line to not appear as long as specified 
by the starting and ending coordinates. If the endstyle selected is POINT, the last 
point of the line is drawn whether it is appropriate or not. In this case, the end- 
points of the line always appear on the screen. If the endstyle selected is 
BEST_FIT, the last point is always drawn but is extended as far back as the last 
space if appropriate. However, the BEST_FIT endstyle may shorten the space 
between the last element of the line and the element preceding the last element 
by one in order to guarantee that the line ends on a drawn point The default 
endstyle is BEST_FIT. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 

VSOP, orVSAC. 

Cerror line_width_specif ication_mode (mode) 

Cspecmode mode; /* pixels or percent */ 

line_width_specif ication_mode ( ) allows the line width to be 
specified in pixels or as a percentage of VDC space according to the value of 
mode. The enumerated type Cspecmode contains values that correspond to 
line width specification modes. 

typedef enum { 

ABSOLUTE, 

SCALED 
} Cspecmode; 

If the line width specification mode is changed from ABSOLUTE to SCALED, the 
change in the line width wiU probably be dramatic. The default line width 
specification mode is SCALED. 

If multiple view surfaces are active, the line width is scaled separately for each 
view surface. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 
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Line Width 



Line Color 



Cerror line_width (index) 

Cfloat index; /* line width */ 

line_width ( ) determines the width of the lines composing polylines, circular 
arcs, and so on. If the line width specification mode is SCALED, index is 
expressed in percent of VDC space, and if the x and y dimensions are different, 
the width is calculated on the basis of the range of the x coordinate of VDC space. 
If the parameter setting would result in a line less than one pixel wide, the line 
width is displayed as one pixel wide. The default line width is 0.0 (SCALED). 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


EBDWIDTH [34] 


Width must be nonnegative. 


Cerror line_color (index) 

Cint index; /* line color */ 


line color ( ) determines the color of the lines, index selects an entry in the 
color lookup table. The default value of index is 1. An error is detected if index 
is not between 0 and 255. 


ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ECINDXLZ [35] 


Color index is less than zero. 


EBADCOLX [36] 


Color index is invalid. 



4.3. Polymarker Attributes The type, size and color of markers (the components of polymarkers) are con- 
trolled by the following functions. 

Polymarker Bundle Index Cerror polymarker_bundle_index (index) 

Cint index; /* polymarker bundle index */ 

polymarker_bundle_index ( ) sets the current polymarker bundle index to 
the value of index. The contents of a polymarker bundle are marker type, marker 
size and marker color. The marker size specification mode function is not 
included in the polymarker bundle. If index is not defined, an error is generated, 
and the polymarker bundle index does not change. If the ASFs for any of these 
attributes is set to BUNDLED, the current values of these attributes are set to the 
values of the corresponding attribute in the bundle. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP.orVSAC. 

EBADMRKX [37] Polymarker index is invalid. 
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Marker Type 



Marker Size Specification 
Mode 



Cerror mark:er_type (type) 

Cmartype type; /* style of marker */ 

marker_type ( ) sets the marker type. The enumerated type Cmartype con- 
tains values that correspond to valid marker types. 

typedef enum { 

DOT, 

PLUS, 

ASTERISK, 

CIRCLE, 

X 

} Cmartype; 

Note that aU marker types appear as a point when the marker size is very small. 
The default marker type is DOT. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

Cerror marker_size_specif ication_mode (mode) 

Cspecmode mode; /* pixels or percent */ 

marker_size_specif ication_mode ( ) allows the marker size to be 
specified in pixels or as a percentage of VDC space according to the value of 
mode. The enumerated type Cspecmode contains values that correspond to 
valid marker size specifications. 

typedef enum { 

ABSOLUTE, 

SCALED 
} Cspecmode; 

The default marker size specification mode is SCALED. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 



Marker Size 



Cerror marker_size ( index) 

Cfloat index; /* marker size */ 



mar ker_s i z e ( ) sets the size of the marker height and marker width, index is 
expressed in percent of VDC space. The default marker size is 4.0 percent of 
VDC space. If the marker size becomes very small, markers of all types are 
displayed as points. An error is detected if index is negative. 



ENOTOPOP [5] 
EBADSIZE [38] 



CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Size must be normegative. 
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Marker Color 



Cerror marker 
Cint index; / 


color (index) 

* marker color */ 


marker_color { ) determines the color of the maricers. index selects an entry 
in the color lookup table. An error is detected if index is not between 0 and 255. 
The default marker color is 1. 


ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ECINDXLZ [35] 


Color index is less than zero. 


EB AD CO LX [36] 


Color index is invalid. 



4.4. Solid Object Attributes The solid object attribute functions describe how all solid object primitives are 

filled (colored-in). There are three sets of solid object attribute functions: 

fill area attributes 

determine the general method for filling solid geometrical objects. 
hatch and pattern attributes 

determine a pixel array for filling a polygon if the fill style is set to PAT- 
TERN. 

perimeter attributes 

determine how the boundary of a geometrical object is displayed if the per- 
imeter visibility is ON. 



Fill Area Bundle Index Cerror fill_area_bundle_index (index) 

Cint index; /* fill area bundle index */ 

f ill_area_bundle_index ( ) sets the current fill area bundle index to the 
value of index. The contents of the fill area bundle are interior style, fill color, 
hatch index, pattern index, perimeter type, perimeter width, and perimeter color. 
The perimeter width specification mode and the pattern attributes are not 
included in the definition of the fill area bundle. If index is not defined, an error 
is generated, and the fill area bundle index does not change. If the ASFs for any 
of these attributes is set to BUNDLED, the current value of the attribute is set to 
the value of the corresponding attribute in the bundle. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBADFABX [39] Fill area index is invalid. 

Interior Style cerror interior_style (istyle, perimvis) 

Cintertype istyle; /* fill style */ 

Cflag perimvis; /* perimeter visibility */ 

interior_style ( ) sets the fill style for solid objects. The enumerated type 
Cintertype contains values that correspond to valid line types. 
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4.5. Solid Interior Fill 
Attribute 

Fill Color 



4.6. Hatch and Pattern 
Attributes 



typedef enum { 

HOLLOW, 

SOLIDI, 

PATTERN, 

HATCH 

} Cintertype; 

If the^i// style is set to SOLIDI, the solid object is filled with the current^// color. 
If istyle is set to PATTERN or HATCH, the solid object is filled with the current 
PATTERN or HATCH style. The PATTERN and HATCH styles are explained in 
the pattern attributes section. The default fill style is HOLLOW. 

inter ior_style ( ) also determines whether the perimeter of the solid object 
is visible according to the value of perimvis (which must be ON or OFF). If per- 
imvis is OFF, the perimeter attributes have no effect. The default value of perim- 
eter visibility is ON. 

Be careful when using the interior style function to explicitly specify the per- 
imvis argument. If you do not specify it, or set it to OFF, the geometrical output 
primitive may not be displayed because the interior style is HOLLOW. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

The following section contains the description of a function that determines the 
color of an interior region if the fill style is not HOLLOW. 

Cerror fill_color (color ) 

Cint color; /* color for solid object fill */ 

f ill_color ( ) determines the color for filling solid objects, if the fill style is 
not set to HOLLOW. 

The default fill style is HOLLOW, so changing the fill color will not have an 
effect without changing the interior style first. The default fill color is 1. An 
error is detected if fill color is not between 0 and 255. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

EC INDXLZ [35] Color index is less than zero. 

EBADCOLX [36] Color index is invalid. 

Geometrical primitives can be filled with 2D arrays of color values called pat- 
terns. SunCGI supports pre-defined as weU as user-defined patterns. Pattern 0 is 
initially defined to be a 3 x 3 matrix which is set to zero at the comers and one 
elsewhere. Pattern 0 produces simple cross-hatching. Pattern 1 (which produces 
a polka-dot pattern) is initially defined to be a 3 x 3 matrix which is set to 1 at the 
center and 0 elsewhere. 
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The definition of patterns is stored in the pattern table. Each entry in the pattern 
table consists of a 2D array of color values and the x and y dimensions of the 
array. The starting position (upper left-hand comer) of the pattern is determined 
by the pattern reference point. 

Two types of patterns are available; PATTERNS and HATCHes; PATTERNS can 
be scaled and translated. HATCHes can’t and simply fill the geometrical output 
primitives with pixel arrays. 

The following example program illustrates how to change the appearance with 
the individual attribute functions. The program draws a polygon and fills it with 
a pattern. 

finclude <cgidefs.h> 

#define BOXPTS 5 

#define PAT_ROWS 4 

#define PAT_COLS 4 

#define PAT_SIZE (PAT_ROWS * PAT_COLS) 

#define PAT_INDEX 2 

#define PAT_DX 250 

fdefine PAT_DY 250 

Ccoor box [BOXPTS] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 }; 

/*Cint pattern [PAT_S I ZE] = { 50, 75, 100, 125, 

150, 0, 0, 175, 

200, 0, 0, 225, 

250, 275, 300, 325 };*/ 

Cint pattern [PAT_SIZE] = { 6, 1, 1, 2, 

7, 0, 0, 3, 

7, 0, 0, 3, 

6, 5, 5, 4 }; 

main ( ) 

{ 

Cint name; 

Cvwsurf device; 

Ccoorlist boxlist; 

boxlist.n = BOXPTS; 
boxlist .ptlist = box; 

NORMAL_VWSURF { device, PIXWINDD) ; 

open_cgi { ) ; 

open_vws ( &name, Sdevice) ; 
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interior_style ( PATTERN, ON) ; 

pattern_table ( PAT_INDEX, PAT_ROWS, PAT_COLS, pattern); 
pattern_index ( PAT_INDEX) ; 
pattern_size ( PAT_DX, PAT_DY) ; 
polygon ( Sboxlist) ; 

sleep (10) ; 

close_vws( name); 
close_cgi { ) ; 

} 

V / 



Hatch Index 



Pattern Index 



Pattern Table 



Cerror hat ch_index (index) 

Cint index; /* HATCH index in the pattern table */ 



hatch_index ( ) determines which entry in the pattern table is used to fill 
solid objects when the fill style is set to HATCH. The default hatch index is 0. 
An error is generated if index points to an undefined entry in the pattern table. 



ENOTOPOP [5] 

EBTBUNDL [30] 
ESTYLLEZ [42] 
ENOPATNX [43] 



CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

ASF is BUNDLED. 

Style (pattern or hatch) index is less than zero. 

Pattern table index not defined. 



Cerror pattern_index (index) 

Cint index; /* PATTERN index in the pattern table */ 

pattern_index ( ) determines which index in the pattern table is used to fill 
solid objects when the fill style is set to PATTERN. The default pattern index is 
1. An error is generated if index points to an undefined entry in the pattern table. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ESTYLLEZ [42] 


Style (pattern or hatch) index is less than zero. 


ENOPATNX [43] 


Pattern table index not defined. 



Cerror pattern_table ( index, m, n, colorind) 

Cint index; /* entry in table */ 

Cint m, n; /* number of rows and columns */ 

Cint *colorind; /* array containing pattern */ 

pattern_table ( ) defines an entry in the pattern table, index defines the 
entry in the table (which must be less than 50). An error is generated if index is 
outside the bounds of the pattern table, m and n define the height and width of 
the pattern (in pixels). The array pointed to by the argument colorind contains 
the actual pattern row-wise from the upper left. For monochrome view surfaces, 
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Pattern Reference Point 



Pattern Size 



Pattern with Fill Color 
(SunCGI Extension) 



all nonzero entries in colorind are treated as 1. The maximum number of ele- 
ments in a pattern (m x n) is MAXPATSIZE. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EPATARTL [40] 


Pattern array too large. 


EPATSZTS [41] 


Pattern size too small. 


ESTYLLEZ [42] 


Style (pattern or hatch) index is less than zero. 


EPATITOL [44] 


Pattern table index too large. 


Cerror pattern_ 
Ccoor *begin; 


_reference_j>oint (begin) 


pattern_ref erence_j)oint ( ) defines the point in VDC space where the 
pattern box begins. The pattern is then replicated over all VDC space. The upper 
left-hand comer of the pattern box is determined by begin. The default pattern 
reference point is (0, 0). pattern_ref erence_point ( ) has no effect if 
the interior style is not set to PATTERN. 


ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


Cerror pattern_ 
Cint dx, dy; /* 


size (dx, dy) 

■ size of pattern in VDC space */ 



pattern_size ( ) defines the size of the pattern array in VDC coordinates, dx 
and dy determine the size of an element of the pattern in VDC space. 
pattern_size ( ) therefore allows you to ‘stretch’ the pattern to a certain 
size. IfdxoTdy would result in pattern elements less than one pixel wide, 1 is 
used. If the pattern size is larger than the bounds of screen space, the effective 
pattern size is the size of VDC space. The default pattern size is (300, 300). 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 



Cerror pattern_with_f ill_color (flag) 

Cflag flag; /* ON to use nonzero pattern 
elements as fill color */ 

Binary patterns allow the same pattern to be applied in different colors, without 
redefining the pattern array. pattern_with_f ill_color ( ) sets a non- 
standard CGI state pattern with fill color. The default pattern with fill color is 
OFF, and each color value in a pattern table entry is used verbatim, as in standard 
CGI. When a pattern is used while pattern with fill color is ON, the pattern is 
considered to be a 2D array of flags; when the pattern element is nonzero, the 
current fill color is used, instead of the actual value of the pattern element. 

(When the pattern element is zero, a zero color index is used, just as when the 
flag is OFF.) 
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4.7. Perimeter Attributes The following sections contain descriptions of functions that determine the per- 
imeter attributes perimeter type, perimeter width, perimeter width specification 
mode, and perimeter color. 

Perimeter Type Cerror perimeter_type (type) 

Clintype type; /* style of perimeter */ 

perimeter_type ( ) defines the perimeter type for solid objects. The 
enumerated type Clintype contains values that correspond to valid perimeter 
types. 

typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 

DASH_DOT_DOTTED , 

LONG_D ASHED 
} Clintype; 

The default perimeter style is SOLID. Notice that there is no ending style for per- 
imeter. The endstyle is controlled by the line_endstyle ( ) function. 

As mentioned previously, control of the drawing of the borders of solid objects is 
under the control of the perimeter attribute functions, not the line attribute func- 
tions. However, the two sets of functions take the same values. The perimeter 
attributes are essentially the same as the line attributes except that they affect the 
borders of solid attributes. The appearance of a perimeter can be similar to a line 
especially if interior style is set to HOLLOW. Perimeter attribute functions have 
no effect if the perimeter visibility is set to OFF. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or vs AC. 

EBTBUNDL [30] ASF is BUNDLED. 



Perimeter Width Cerror per imeter_width (width) 

Cfloat width; /* perimeter width */ 

perimeter_width ( ) determines the width of the perimeters of solid objects. 
index can be expressed in percent of VDC space or pixels. If the perimeter width 
specification mode is set to SCALED and the x and y dimensions are different, the 
perimeter width is calculated on the basis of the range of the x coordinate of VDC 
space. If the parameter setting would result in a perimeter less than one pixel 
wide, the perimeter width is displayed as one pixel wide. The default perimeter 
width is 0.0 (SCALED). 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 




EBDWIDTH [34] 


Width must be nonnegative. 
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Perimeter Width Specification Cerror perimeter_width_specification_mode (mode) 

Mode Cspecmode mode; /* pixels or percent */ 

perimeter_width_specification_mode () allows the 
perimeter_width ( ) to be specified in pixels or as a percentage of VDC 
space according to the value of mode (which can either be ABSOLUTE or 
SCALED). If the perimeter width specification mode is changed from ABSO- 
LUTE to SCALED, the change in the line width will probably be dramatic. The 
default perimeter width specification mode is SCALED. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Perimeter Color Cerror perimeter_color (index) 

Cint index; /* perimeter color */ 

per imeter_color ( ) determines the color of the perimeters, index selects 
an entry in the color lookup table. The default value of index is 1. An error is 
detected if index is not between 0 and 255. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 




VSOP, or VSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ECINDXLZ [35] 


Color index is less than zero. 


EBADCOLX [36] 


Color index is invalid. 



4.8. Text Attributes SunCGI provides a variety of functions for determining how text is written to the 

screen. The most important text attribute is text precision. If text precision is set 
to STRING, firmware characters are used. The fonts, size, spacing, and alignment 
of firmware are more limited than characters drawn with text precision set to a 
value other than STRING. Therefore, calls to text attribute functions regulating 
these aspects of text drawing have no effect when text precision is set to STRING. 

Text Bundle Index Cerror text_bundle_index (index) 

Cint index; /* text bundle index */ 

text_bundle_index ( ) sets the current text bundle index to the value of 
index. The contents of the text bundle index are text font, text precision, charac- 
ter expansion factor, character spacing, and text color. The character height, 
character orientation, character path, text alignment, and fixed font are not 
included in the definition of the text bundle. If index is not defined, an error is 
generated, and the text bundle index does not change. If the ASFs for any of 
these attributes are set to BUNDLED, the current values of these attributes are set 
to the contents of the bundle. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBADTXTX [45] Text index is invalid. 
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Text Precision 



Character Set Index 



Text Font Index 



Cerror text_precision (type) 

Cprectype type; /* text type */ 

text_j>recision ( ) controls the precision with which text is displayed. The 
enumerated type Cprectype contains values that correspond to valid text pre- 
cisions. 

typedef enum { 

STRING, 

CHARACTER, 

STROKE 
} Cprectype; 

If the text precision is set to STRING, the firmware character set is used. 
Firmware characters cannot be scaled or rotated. 

Characters are clipped, but not in parts (that is, if any portion of the character 
exceeds the clipping boundary the whole character is clipped). If the text preci- 
sion is set to CHARACTER, software generated characters are employed, and 
characters are clipped, but not in parts. All text attributes have a visible effect on 
software generated characters. If the text precision is set to STROKE, the CHAR- 
ACTER precision capabilities are enabled, and characters are clipped in parts. 

The default text precision is STRING. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

Cerror character_set_index (index) 

Cint index; /* font set */ 

character_set_index ( ) selects a set of fonts. Although SwnCG/ supports 
this function, only set number 1 is defined. Calls to 

character_set_index ( ) with index assigned to a value other than 1 are 
ignored. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Cerror text_font_index (index) 

Cint index; /* font */ 

text_f ont_index ( ) determines the current font. A list of available fonts 
and their availability when text precision is set to STRING is given in Table 4-3. 
A warning about the SYMBOL font: undefined characters are displayed as bugs 
(the six-legged kind). The default font is STICK. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ETXTFLIN [47] 


Text font is invalid. 
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Table 4-3 Available Fonts 



Font 


String Precision 


Font Number 


ROMAN 


Yes 


0 


GREEK 


Vest 


1 


SCRIPT 


Yes 


2 


OLDENGLISH 


No 


3 


STICK 


Yes 


4 


SYMBOLS 


No 


5 



t displayed as STICK font. 



Character Expansion Factor Cerror character_expansion_f actor (efac) 

Cfloat efac; /* width factor */ 

character_expansion_f actor ( ) determines the width-to-height ratio of 
characters. If efac is greater than 1 the characters appear fatter. If ^ac is less 
than 1 the characters appear slimmer. The default character expansion factor is 
1.0. An error is generated if efac is less than 0.01 or greater than 10. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECEXFOOR [48] Expansion factor is out of range. 

Character Spacing Cerror character_spacing (spcratio) 

Cfloat spcratio; /* spacing ratio */ 

character_spacing { ) sets the spacing between characters based on the 
height of the characters. The amount of space between characters is obtained by 
multiplying the character height by spcratio. The default character spacing fac- 
tor is 0. 1 . An error is generated if spcratio is less than - 10 or greater than 10. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECEXFOOR [48] Expansion factor is out of range. 

Character Height Cerror character_height (height) 

Cint height; /* height in VDC */ 

The char act er_height ( ) function determines the height of text in VDC 
units. The height is defined as the distance from the top to the bottom of the 
character. Notice that changing the character height implicitly changes the char- 
acter spacing. 

The default character height is 1000. This may result in huge characters if VDC 
space is reset from its default range (0-32767). 
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Fixed Font (SunCGI 
Extension) 



Text Color 



Character Orientation 



If the X and y dimensions of VDC space are different, the height is calculated on 
the basis of the range of the x coordinate of VDC space. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECHHTLEZ [49] Character height is less than or equal to zero. 

Cerror f ixed_f ont (f lag) 

Cint flag; /* fixed or variable width characters */ 

f ixed_f ont ( ) allows characters to be of fixed or variable size. If Jlag is 
nonzero, the characters are of uniform size, otherwise the characters are packed 
proportional to their actual sizes. If the character precision is STRING, this func- 
tion has no effect. By default SunCGI supports variable width characters. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Cerror text_color (index) 

Cint index; /* color */ 

text_color ( ) determines the color of the text, index selects an entry in the 
color lookup table. The default value of index is 1 . An error is detected if index 
is not between 0 and 255. 



ENOTOPOP [5] 


CGI not in proper state: CGI should be in state CGOP, 




VSOP, orVSAC. 


EBTBUNDL [30] 


ASF is BUNDLED. 


ECINDXLZ [35] 


Color index is less than zero. 


EBADCOLX [36] 


Color index is invalid. 



Cerror character_orientation (xbase, ybase, xup, yup) 

Cfloat xbase, ybase, xup, yup; 

/* character base and up vectors */ 

character_orientation ( ) specifies the skew and direction of text. The 
left side of the character box lies on an invisible line called the character up vec- 
tor, whose slope is detennined by xup and yup. The bottom of the character box 
lies on an invisible line caUed the character base vector, whose slope is deter- 
mined by xbase and ybase. 

If the character up vector and the character base vector are not orthogonal, the 
text is distorted. Calls to character_or ientation ( ) have no effect if text 
precision is set to STRING. The default values for the character base vector and 
the character up vector are xbase = 1.0, ybase = 0.0, xup = 0.0, and yup = 1.0. 

The character base vector and the character up vector influence the character 
path and the text alignment. For example, if xbase = -1.0 and the character path 
is RIGHT, the text is written to the /e/t. 




microsystems 



Revision A, of 9 May 1988 




74 SunCGI Reference Manual 



Character Path 



Text Alignment 



ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 

VSOP, orVSAC 

ECHRUPVZ [50] Length of character up vector or character base vector is 
zero. 



Cerror character_path (path) 

Cpathtype path; /* text direction */ 

character_path ( ) specifies the direction in which text is written. The 
emunerated type Cpathtype contains values that correspond to valid character 
paths. 

typedef enum { 

RIGHT, 

LEFT, 

UP, 

DOWN 

} Cpathtype; 

The actual effect of character_path ( ) depends on the character up vector 
and the character base vector. RIGHT specifies that the text is written in the 
direction of the character base vector. For example, if the direction of the char- 
acter base vector points left instead of right (xup = -1.0 instead of 1.0), the text 
will be written right-to-left instead of left-to-right, which is the usual inteipreta- 
tion of RIGHT. LEFT specifies that the text is written in the opposite direction of 
the character base vector. The character up vector and character base vector 
essentially change fiinctions when the character direction is set to UP or DOWN. 
UP specifies that the text is written in the direction of the character up vector. 
DOWN specifies that the text is written in the opposite direction of the character 
up vector. The default character path is RIGHT. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Cerror text_alignment (halign, valign, hcalind, vcalind) 
Chaligntype halign; /* horizontal alignment type */ 
Cvaligntype valign; /* vertical alignment type */ 

Cfloat hcalind, vcalind; 

/* continuous alignment indicators */ 

text_alignment ( ) determines where the text is positioned relative to the 
starting point specified by the cl argument of the text { ) or vdm_text { ) 
function, halign determines where the character is placed in relation to the x 
component of the starting coordinate of the text position (specified by the cl 
argument of text). The enumerated type Chaligntype contains values that 
correspond to valid horizontal alignments. 




microsystems 



Revision A, of 9 May 1988 





Chapter 4 — Attributes 7 5 



typedef enum { 

LFT, 

CNTER, 

RGHT, 

NRMAL, 

CNT 

} Chaligntype; 

If the value of halign is LFT, the horizontal position of the text will begin at the 
left edge of the box enclosing the text. Similarly, if the value of halign is RGHT, 
the horizontal position of the text will begin at the right edge of the box enclos- 
ing the text. If the value of halign is CNTER the horizontal position of the text 
will begin equidistant from the right and the left edges of the text box. NRMAL 
assigns the alignment based on the value of the character path (see Table 4-4). 

If the value of halign is CNT (continuous) the horizontal position of the text is 
determined by the argument hcalind. In this case, the text will begin hcalind 
fraction of the width of the text box from the left edge of the character box. The 
default value of halign is NRMAL. 

valign specifies where the character is placed in relation to the y component of 
the text position. The enumerated type Cvaligntype contains values that 
correspond to valid vertical alignments. 

typedef enum { 

TOP, 

CAP, 

HALF, 

BASE, 

BOTTOM, 

NORMAL, 

CONT 

} Cvaligntype; 

If the value of valign is TOP, the vertical position of the text will begin at the top 
edge of the character box. If the value of valign is CAP, the vertical position of 
the text will begin at the cap line of the character.^^ Similarly, if the value of 
valign is BOTTOM, the vertical position of the text wiU begin at the bottom edge 
of the character box. If the value of valign is BASE, the vertical position of the 
text will begin at the baseline of the character. If the value of valign is HALF 
the vertical position of the text will begin equidistant from the top and the bottom 
edges of the character box. NORMAL assigns the alignment based on the value 
of the character path (see Table 4-4). If the value of valign is assigned to CONT 
(continuous), the vertical position of the text is determined by the argument 
vcalind and will begin vcalind fraction of the height of the character box from the 
bottom edge of the character box. The default value of valign is NORMAL. 



The cap line is defined as the invisible line corresponding to the top of the average character within a font. 

The baseline is defined as the invisible line correspx>nding to the bottom of the average character within a 
font. The baseline does not necessarily correspond to the bottom of a character. For example, a the tail of a 
lower-case g extends below the baseline. 
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Table 4-4 Normal Alignment Values 



Character 

Path 


Horizontal 

Normal 


Vertical 

Normal 


RIGHT 


LEFT 


BASELINE 


LEFT 


RIGHT 


BASELINE 


UP 


CENTER 


BASELINE 


DOWN 


CENTER 


TOP 



ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

4.9. Color Attributes SunCGI supports only one color specification mode — INDEXED. This color 

specification mode means that the red, green, and blue values (hereafter referred 
to as RGB values) are obtained from a table known as the color lookup table. 
The initial values of the color lookup table are provided in Table 4-5. 

Table 4-5 Default Color Lookup Table 



Index 


Color 


RGB Intensities 


0 


black 


0,0,0 


1 


red 


255, 0, 0 


2 


yellow 


128, 128, 0 


3 


green 


0, 255, 0 


4 


cyan 


0, 128, 128 


5 


blue 


0, 0, 255 


6 


magenta 


128, 0, 128 


7 


white 


255, 255, 255 



Color Lookup Table Cerror color_t able (1st art ^ clist) 

Cint istart; /* starting address */ 

Ccentry *clist; /* color triples and number of entries */ 

color_table ( ) defines RGB entries into the color lookup table used by CGI. 
The color lookup table is initialized based on the depth of the display frame 
buffer, the cmapsize field provided in the Cvwsurf structure provided to 
open_vws ( ) , and the colormap defined by the RGB arrays. Before you can 
modify the color lookup table, both the cmapsize and cmapname fields provided 
in the Cvwsurf structure must be initialized 

A monochrome device has an unwritable colormap; non-zero color indices are 
displayed as black, zero is displayed as white. A color device gets a colormap 
segment with 8 entries if the cmapsize field is zero upon opening the view sur- 
face. Larger colormaps are also initialized to a power of 2, even if you are not 
going to initialize all entries in the colormap. 

The structure Ccentry contains elements that describe a colormap entry. 
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typedef struct { 

unsigned char *ra; 
unsigned char *ga; 
unsigned char *ba; 

Cint n; 

} Ccentry; 

The minimum and maximum color lookup table entries are treated specially by 
SunView and hence by SunCGI. If they are set to be the same value, the user’s 
values for these two entries are both ignored. They revert to the inverse of the 
normal values; entry 0 becomes white, the maximum entry becomes black. 

The argument istart determines the first entry in the color lookup table to be 
modified. The argument clist contains the color information for entry istart in 
terms of triples of values of numbers ranging between 0 and 255. The last field 
of clist reports how many entries are to be modified. An error is generated if 
either the indices to the color lookup table are out of range. 

The following steps describe how to set up a color lookup table in SunCGI. 

1. Set up the RGB arrays of colors. The number of elements in each array 
must be a power of 2. Each array must have intensities that range from 0 to 
255; 255 represents a strong intensity of that color, and 0 is no intensity. 

A color is defined by the RGB array elements for that index of the color. 
For example, color element 3 is the color defined by red(3), green(3), and 
blue(3). 

2. Set the RGB arrays into the Ccentry stmcture. 

3. Call the color_table ( ) function to set the colors in the color lookup 
table. 

To later change the color lookup table, update the RGB arrays and call 
color_table ( ) . See Appendix E for an example program. 

To set or change a color lookup table in CGIPW, use the pw_putcolormap ( ) 
function. This function is described in detail in the SunView 1 Programmer's 
Guide. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

ECINDXLZ [35] Color index is less than zero. 

EBADCOLX [36] Color index is invalid. 

4.10. Inquiry Functions The attribute inquiry functions permit examination of the current attributes. 

Attributes are reported in groups corresponding to the class of output primitive 
they modify. The argument to each inquiry function has its own structure type 
which has an element for each of the individual attributes (see Appendix B). 
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Inquire Line Attributes Clinatt *inquire_line_attributes () 

/* returns a pointer to line attribute structure */ 

inquire_line_attributes { ) reports the current line style, line width, 
line color, and polyline bundle index in the appropriate elements of the returned 
value of the fimction. 

typedef struct { 

Clint ype style; 

Cfloat width; 

Cint color; 

Cint index; 

} Clinatt; 

inquire_line_attributes ( ) returns a NULL (not an error number) in 
case of errors. Errors are printed if the error warning mode is not set to 
NO_ACTION. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Inquire Marker Attributes Cmarkatt *inquire_marker_attributes () 

/* returns a pointer to marker attribute structure */ 

inquire_marker_attributes { ) reports the current marker style, marker 
width, marker color, and polymarker bundle index in the appropriate elements of 
the returned value of the function. 

typedef struct { 

Cmartype type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

inquire_marker_att ribut es ( ) returns a NULL (not an error number) in 
case of errors. Errors are printed if the error warning mode is not set to 
N0_ACT10N. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Inquire Fill Area Attributes Cf illatt *inquire_f ill_area_attributes ( ) 

The current interior style, perimeter visibility , fill color, hatch index, pattern 
index, fill area bundle index, perimeter style, perimeter width, and perimeter 
color can be obtained by using the inquire_f ill_area_attr ibutes ( ) 
function. 
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typedef struct { 

Cintertype style; 

Cflagtype visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_index; 

Cint index; 

Clintype pstyle; 

Cfloat pwidth; 

Cint pcolor; 

} fillatt; 

i nqu i r e_f i 1 l_a.r e a_at t r ibu t e s ( ) returns a NULL (not an error 
number) in case of errors. Errors are printed if the error warning mode is not set 
to NO_ACTION. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

Inquire Pattern Attributes Cpatternatt *inquire__pattern_attributes () 

/* returns a pointer to pattern attribute structure */ 

inquire_pattern_attr ibutes ( ) reports the current pattern index, row 
count, column count, color list, pattern reference point, and pattern size. 

typedef struct { 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

} patternatt; 

inquire_pattern_attr ibutes { ) returns a NULL (not an error number) 
in case of errors. Errors are printed if the error warning mode is not set to 
NO_ACTION. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Inquire Text Attributes Ctextatt *inquire_text_attr ibutes ( ) 

/* returns a pointer to text attribute structure */ 

inquire_text_attr ibutes ( ) reports the current font set, text bundle 
index, font, text precision, character expansion factor, character spacing, text 
color, character height, character base vector, character up vector, character 
path, and text alignment. 
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typedef struct { 

Cint fontset; 

Cint index; 

Cint current_font; 

Cprectype precision; 

Cfloat exp_factor; 

Cfloat space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

} textatt; 

inquire_text_attributes ( ) returns a NULL (not an error number) in 
case of errors. Errors are printed if the error warning mode is not set to 
NO_ACTION. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 

VSOP, orVSAC. 

Inquire Aspect Source Flags Cf laglist *inquire_aspect_source__f lags ( ) 

/* returns a pointer to text attribute structure */ 

inquire_aspect_source_f lags { ) reports whether attributes are set 
individually by returning all of the values of the ASFs. The element n of the 
flaglist struct is set to 18. The definitions of each flag are in Table 4-2. 

typedef struct { 

Cint n; 

Cint *num; 

Casptype *value; 

} Cflaglist; 

inquire_aspect_source_f lags ( ) returns a NULL (not an error 
number) in case of errors. Errors are printed if the error warning mode is not set 
to NO_ACTION. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 
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5.1. Input Device Initialization 

Initialize LID 

Release Input Device 

Associate 

Set Default Trigger Associations 

Dissociate 

Set Initial Value 

Set VALUATOR Range 

Track On 

Track Off 

5.2. Synchronous Input 

Request Input 

5.3. Asynchronous Input 

Initiate Request 

5.4. Event Queue Input 

Enable Events 

Await Event 

Flush Event Queue 

Selective Flush of Event Queue . 

5.5. Miscellaneous Input Functions 

Sample Input 

Get Last Requested Input 



Disable Events 99 

5.6. Status Inquiries 99 

Inquire LID State List 99 

Inquire LID State 100 

Inquire Trigger State 100 

Inquire Event Queue State 100 




Input 



CGI has a collection of functions for managing input devices. The design of 
these ftmctions has two purposes: provide an interface close to the actual input 
device and maintain portability of applications. CGI accomplishes the first goal 
with different input device classes and methods of extracting input values. The 
second goal is achieved through CGI’s model of logical input devices (LID), an 
abstraction whereby logical input devices required by the CGI standard are 
mapped onto the physical devices available to a CGI implementation. This 
chapter will introduce some of the terms used in describing the functionality of 
the CGI input primitives. 

A CGI input device consists of a measure associated with a trigger. A measure is 
the current value of a logical input device. For example, the IC_LOCATOR dev- 
ice reports an x-y position. This device is useful for determining a position on 
the screen. A trigger is a physical device used by an operator to accept a current 
value. A trigger fire corresponds to an event on a physical input device. At the 
request of the application program, SunCGI associates a measure with a trigger. 
Table 5-1 has a list of the five logical input devices available to SunCGI applica- 
tion programs and the available triggers. For example, a mouse button on a Sun 
workstation is a trigger that can be associated with a IC_LOCATOR device. 

When the mouse button is pressed, the x-y position of the mouse is returned as 
the measure of the IC_LOCATOR input device. 

An input event is the information saved when a trigger fires. This includes the 
measure of a logical input device associated with a trigger. 
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Table 5-1 Input Devices Offered by SunCGI 



Device 

Class 


Measure 


Trigger 

Number 


Trigger 


ic_ux:ator 


x-y position in VDC 


2 


Left mouse button 




space. 


3 


Middle mouse button 






4 


Right mouse button 






5 


Mouse movementt 






6 


Mouse stiU$ 


IC_STROKE 


Array of x-y points in 


2 


Left mouse button 




VDC space. 


3 


Middle mouse button 






4 


Right mouse button 


IC_VALUATOR 


Noraaalized x position 


2 


Left mouse button 






3 


Middle mouse button 






4 


Right mouse button 






5 


Mouse movement 






6 


Mouse stiU 


IC_CHOICE 


A non-negative integer 


2 


Left mouse button 




that identifies which 


3 


Middle mouse button 




mouse button was 
pressed. Zero 
represents "no choice". 


4 


Right mouse button 


IC_STRING 


Character string. 


1 


Keyboard input ter- 
minated a carriage 








return. 



t The Mouse Movement trigger fires when the mouse moves. 

$ The Mouse Still trigger fires when the mouse does not move for one 
fifth of a second or more. 



The graphical method with which the measure of an input device is displayed is 
called tracking. SunCGI provides several methods of tracking for each input 
device. Table 5-3 has a list of track types available for each input device class. 
Tracking must be explicitly enabled for each device. 

Each input device can be in one of the five states described pictorially in Figure 
5-1. The state of an input device determines the marmer in which the application 
program retrieves the measure of the input device. The input functions that allow 
a change of state are listed next to the arrows indicating the state change. 
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Figure 5-1 CGI Input State Model 




RELEASED 

Before an input device is initialized, it is in the RELEASED state. Any input 
function (except initialization) will generate an error in this state. 

NO_EVENTS 

After an input device has been initialized, it is in the NO_EVENTS state. An 
application program can extract an input value of an input device in 
NO_EVENTS state. This will result in either the value that the device was 
initialized with or the value the device had when it was in a state where it 
could process events. This is not necessarily the current measure of the dev- 
ice and does not change while the device is in this state. 

RESPOND_EVENT 

The RESPOND_EVENT state corresponds with synchronous communication 
between the process that controls the input device and the application pro- 
gram. When an application program requests the measure of an input device 
in RESPOND_EVENT state, SunCGI blocks program execution until it can 
fulfill the request. The request_input ( ) function wiU return when the 
trigger fires and the input request is satisfied or after a timeout period. The 
input device then reverts to NO_EVENTS state. 
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5.1. Input Device 
Initialization 



Initialize LID 



The function that requests input and puls the input device in 
RESPOND_EVENT state is request_input ( ) . When the trigger associ- 
ated with an input device in RESPOND_EVENT state fires, the measure of 
that input device is then stored in the request register as weU as returned by 
the request_input () function. 

REQUEST_EVENT 

The REQUEST_EVENT state corresponds with asynchronous communication 
between the process that controls the input device and the application pro- 
gram. When an application samples an input device, input handling and pro- 
gram execution continue in parallel. Either the requested trigger fires or an 
explicit request is made to disable event processing and return the device to 
NO_EVENTS state. 

When the trigger associated with an input device in REQUEST_EVENT state 
fires, the measure of that input device is then stored in the request register, a 
buffer with one element per device. The request register can be then be read 
with get_last_requested_input ( ) . 

QUEUE_EVENT 

When a device is in QUEUE_EVENT mode, events associated with the indi- 
cated device are appended to the event queue, a first-in, first-out (FIFO) 
buffer shared by all input devices. After calling enable_e vents ( ) , the 
SunCGI application retains program control. While an input device is in 
QUEUE_EVENT mode, events are simultaneously added to the event queue 
when the program executes. 

await_event ( ) returns the event at the head of the event queue. If the 
queue is empty, await_event ( ) wiU wait for the designated trigger to 
fire or a timeout. The application program must process this queue in a 
timely fashion or it will overflow. The event queue can be flushed com- 
pletely or for a specific device. The application program must make an 
explicit request to disable event queue processing and return an input device 
to NO_EVENTS state. 

Before input can be processed, an input device must be initialized and associated 
with a trigger. Input device initialization requires at least one active view sur- 
face. Typically, the procedure for initializing an input device includes calls to 
the initialize_lid() and associate ( ) functions, which turn on an 
input device and associate it with a specific trigger. 

Cerror initialize_lid (devclass, devnum, ival) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cinrep *ival; /* initial value of device measure */ 

initialize_lid ( ) initializes an input device and changes its state from 
RELEASED to NO_E VENTS. This function must be called for an input device 
before it can be referenced by any other input function. The argument devclass 
specifies the desired type of input value, devnum indicates the number of the 
device within that class. The argument ival sets the initial measure of the device. 
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The Cinrep structure contains different elements for each type of measure. The 
appropriate element of Cinrep must be set or an error will be generated. 

typedef struct { 

Ccoor *xypt; /* LOCATOR */ 

Ccoorlist *points; /* STROKE devices */ 

Cfloat val; /* VALUATOR device */ 

Cint choice; /* CHOICE devices */ 

Cchar *string; /* STRING device */ 

Cpick *pick; /* PICK devices (unsupported) */ 

} Cinrep; 

For example, in a L(X!ATOR device initialization, the xypt field of Cinrep must 
be set to the address of a Ccoor allocated by the application program before the 
X and y elements can be set. 

Notice that whenever a device is initialized, no associations with triggers are 
made. This must be done by having the application program call the appropriate 
functions. An error is generated by initialize_lid ( ) if the device does 
not exist, if it is already initialized, or if the initial value is out of range. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VS AC. 

EINDNOEX [80] Input device does not exist. 

EINDALIN [82] Input device already initialized.^^ 

EB AD DATA [95] Contents of input data record are invalid. 

ESTRS I ZE [96] Length of initial string is greater than the implementation 

defined maximum. 

Release Input Device Cerror release_input_device (devclass^ devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

release_input_device ( ) releases all associations between a device and 
its triggers, and removes all pending events for the device from the event queue. 
release_input_device ( ) changes the state of the specified input device 
from NO_E VENTS to RELEASED. An error is produced if devclass and devnum 
do not refer to an existing and initialized device. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINDNOEX [80] Input device does not exist. 

E IND INI T [81] Input device not initialized. 



The ANSI standard allows initialized input devices to be re-initialized. SunCGI does not because it is felt 
that re-initialization is usually a mistake. 
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Associate 



Set Default Trigger 
Associations 



Cerror associate (trigger, devclass, devnum) 
Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 



associateO links a trigger with a specific device. The trigger numbers 
available for each device are listed in Table 5-1. Multiple associations are 
allowed; however, some associations are not allowed (for example, 
IC_LCK:aT 0R may not be associated with the keyboard). 



The interaction between an IC_STROKE device and the trigger requires some 
additional explanation. IC_STROKE can only be associated with the mouse but- 
tons. The first coordinate in the IC_STROKE array is entered when the mouse 
button is initially pressed; the last coordinate is entered when the mouse button is 
released. For IC_LOCATOR and IC_VALUATOR devices, the measure is reported 
when the mouse button is pressed. 



ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 
EINASAEX [83] 
EINAIIMP [84] 
EINTRNEX [86] 



CGI not in proper state: CGI should be in state VSAC. 
Input device does not exist. 

Input device not initialized. 

Association already exists. 

Association is impossible. 

Trigger does not exist. 



Cerror set_default_trigger_associat ions (devclass, devnum) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

set_def ault_trigger_associations ( ) associates a device with a 
default trigger. The default associations are listed in Table 5-2. The rules for 
trigger association are die same as those for the associate ( ) function. 



T able 5 -2 Default T rigger Associations 



Device 

Class 


Trigger 

Number 


Trigger 


IC.LOCATOR 


5 


Mouse position 


IC_STROKE 


4 


Right mouse button 


IC_VALUATOR 


3 


Middle mouse button 


IC_CHOICE 


2 


Left mouse button 


IC_STRING 


1 


Keyboard 



ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 



CGI not in proper state: CGI should be in state VSAC. 
Input device does not exist. 

Input device not initialized. 
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Dissociate 



Set Initial Value 



EINASAEX [83] 


Association already exists. 


EINTRNEX [86] 


Trigger does not exist. 


Cerror dissociate (trigger, devclass, devnum) 


Cint trigger; 


/* trigger number */ 


Cdevoff devclass 


; /* device type */ 


Cint devnum; 


/* device number */ 


dissociate ( } removes the association between a trigger and a specified dev- 
ice. If dissociate { ) is called while there are events pending in the event 
queue for the dissociated device, the pending events are discarded. 


ENOTVSAC [4] 


CGI not in proper state: CGI should be in state VS AC. 


EINDNOEX [80] 


Input device does not exist. 


EINDINIT [81] 


Input device not initialized. 


EINNTASD [85] 


Association does not exist. 


EINTRNEX [86] 


Trigger does not exist. 


Cerror set initial value (devclass , devnum, value) 


Cdevoff devclass 


; /* device type */ 


Cint devnum; 


/* device number */ 


Cinrep *value; 


/* device value */ 


set_initial_value ( ) sets the current measure of a specified device. This 
fimction resets the position of the track, if the track is appropriate and activated. 
set_initial_value ( ) also resets the request register. 


A pointer element of the Cinrep structure must be set to the address of an 
application program allocated area before the values can be set. 


cinrep ivalue; 
point. X = 16384; 
point. y = 16384; 




ivalue. xypt = &point; 


ENOTVSAC [4] 


CGI not in proper state: CGI should be in state VS AC. 


EINDNOEX [80] 


Input device does not exist. 


EINDINIT [81] 


Input device not initialized. 


EBADDATA [95] 


Contents of input data record are invalid. 


ESTRSIZE [96] 


Length of initial string is greater than the implementation 
defined maximum. 
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Set VALUATOR Range 



Track On 



Cerror set_valuator_range (devnum, vmin, vmax) 

Cint devnum; /* device nxomber */ 

Cfloat vmin, vmax; /* limits of VALUATOR */ 

set_valuator_range ( ) specifies the limits of the IC_VALUATOR. Device 
coordinates are mapped into the IC_VALUATOR range. IC_VALUATOR events 
already on the event queue are not rescaled. These events must be dequeued with 
either the selective_flush_of_event_queue () function or 
f lush_event_queue (). 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 

E INDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 



Cerror track_on (devclass, 
trackregion, value) 
Cdevoff devclass; 

Cint devnum; 

Cint tracktype; 

Ccoorpair *trackregion; 
Cinrep *value; 



devnum, tracktype, 

/* device type */ 

/* device number */ 

/* track number */ 

/* window for tracking */ 
/* device value */ 



Tracking fimctions determine how the measure of an input device is displayed on 
the view surface. Each class of devices has its own set of possible tracks (given 
in Table 5-3). Although SunCGI allows certain classes of devices to track simul- 
taneously, all types of input devices are not aUowed to track at once. Tracking is 
not provided in the NO_EVENTS state unless the track type is PRINTERS_FIST. 

track_on ( ) initiates track (or echo) for a specific device. The tracktype argu- 
ment specifies the type of track to be used. The trackregion argument is not 
used; the device tracks in all areas of the view surface. The argument \alue is 
used to initialize tracking. The track is initially displayed on the first view sur- 
face opened. 

The xypt element of the Cinrep structure must be set to the address of an appli- 
cation allocated Ccoor and the Ccoor ’s x andy fields are set to position the 
cursor. The reference point for IC_STROKE echos 2 through 5 is the first point in 
the STROKE array. The reference point for STRING_TRACK echo is the 
append_text ( ) concatenation point, and can be changed by calling text { ) 
or append_text ( ) . 



ENOTVSAC [4] 


CGI not in proper state: CGI should be in state VSAC. 


EINECHON [88] 


Track already on. 


EINETNSU [91] 


Track type not supported. 


EBADDATA [95] 


Contents of input data record are invalid. 


ESTRSIZE [96] 


Length of initial string is greater than the implementation 
defined maximum. 
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Table 5-3 


Available Track Types 


Device 

Class 


Number 


Track Type^ 


Description 


IC_LOCATOR(dd 


<0 


NO_ECHO 


Default cursor. 




1 


PRINTERS_nST 


Designate the current position of the IC_LOCATOR dev- 
ice with a printer’s fist cursor. 


IC_STROKEt 


<0 


NO_ECHO 


Default cursor. 




1 


PRINTERS.nST 


Designate the current position of the 1C_STR0KE device 
with a printer’s fist cursor. 




2 


SOUD.LINE 


Draw a line from the origin to the current position in the 
STROKE array. 




3 


X_LINE 


Draw a line from the A:-axis to the current position in the 
STROKE array. 




4 


Y_LINE 


Draw a line from the y-axis to the current position in the 
STROKE array. 




5 


RUBBER_BAND_BOX 


Designate the current position of the IC_STROKE device 
with a rubber band line connecting the initial position 
and the current position in the STROKE array. 


IC_VALUATORt 


<0 


NO_ECHO 


Default cursor. 




1 


PRINTERS.nST 


Indicate the state of the IC_VALUATOR device with a 
printer’s fist cursor. 




2 


STRING_TRACK 


Display a digital representation of the current 
IC_VALUATOR value. 


IC_CHOICEt 


<0 


NO_ECHO 


Default cursor. 




1 


PRINTERS_nST 


Indicate the state of the IC_CHOICE device with a 
printer’s fist cursor. 


IC_STRING# 


<0 


NO.ECHO 


Default cursor. 




1 


PRINTERS_F1ST 


Indicate the state of the IC_STRING device with a 
printer’s fist cursor. 




2 


STRING_TRACK 


Display the current STRING value. 



t The values listed in the Track Type column are contained in the enumerated type Cechotype returned in 
the Cstatelist structure by inquire_lid_state_list ( ) . They are nor used by track_on ( ) to 
define a track type. 

$ This is a mouse device. 

♦ This is a keyboard device. 

Track Off Cerror track_of f (devclass, devnum, tracktype, action) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint tracktype; 

Cfreeze action; 

track_of f ( ) terminates tracking for a specified input device. The tracktype 
and the action arguments are always ignored. 
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ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 



CGI not in proper state: CGI should be in state VSAC. 
Input device does not exist. 

Input device not initialized. 



5.2. Synchronous Input The synchronous input fiinction request_input () aUows the application 

program to obtain the current measure an of input device. This function requires 
explicit identification of an input device (through theassociateO function). 

The following example program illustrates how to use the synchronous input 
fimctions to get information from an input device. First, an IC_LOCATOR device 
is initialized and associated with a trigger (the left mouse button). The tracking 
method for the IC_LOCATOR is defined to be a printer’s fist. Then measure of 
the IC_LOCATOR is requested with a timeout period of ten seconds. If the 
trigger is activated during this period, request_input ( ) returns a valid 
measure in lvalue. Finally, the IC_LOCATOR is dissociated from the mouse but- 
ton and released. The program exits. 



/* NOTE: This example should be run from a grfxtool. */ 

#include <stdio.h> 

#include <cgidefs.h> 



#define TEN_SECS 
#define LID_LOC 
#define MOUSE_BUTTON_l 
tdefine MOUSE_BUTTON_2 
tdefine MOUSE_BUTTON_3 
#define MOUSE MOVE 



(10 * 1000 * 1000 ) 
1 
2 

3 

4 

5 



main ( ) 
{ 



static Ccoor 
static Cinrep 
Cawresult 
Cint 

Cvwsurf 

char 



ipt = { 16384, 16384 }; 

lvalue = { &ipt, NULL, 0., 

valid; 

name, 

trigger; 

device; 

dummy, buf [80] ; 



/* initial pt */ 

0, ' NULL }; /* init LID */ 



fprintf (stderr, "Move cursor in graphics area & click mouse buttons. 0); 
fprintf (stderr, "To exit, press mouse button three (right). 0); 

NORMAL_VWSURF ( device, PIXWINDD) ; 



open_cgi ( ) ; 

open_vws ( &name, Sdevice) ; 



initialize_lid ( IC_LOCATOR, LID_LOC, & lvalue ) ; /* create locator dev */ 
associate (MOUSE_BUTTON_l, IC_LOCATOR, LID_LOC) ; /* trigger = button 1 */ 
associate (MOUSE_BUTTON_2, IC_LOCATOR, LID_LOC) ; /* trigger = button 1 */ 
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associate (MOUSE_BUTTON_3, IC_LOCATOR, LID_LOC) ; /* trigger = button 1 */ 
associate (MOUSE_MOVE, IC_LOCATOR, LID_LOC) ; /* trigger = button 1 */ 

do { /* loop until get bad data or hit right mouse button */ 

request_input (IC_LOCATOR, LID_LOC, TEN_SECS, 

&valid, Sivalue, fitrigger) ; 
sprintf (buf , "X= %d Y= %d valid= %d trig= %d0, 
ipt.x, ipt.y, valid, trigger); 
fprintf (stderr, "%s", buf ) ; 

} while (valid == VALID_DATA && trigger != MOUSE_BUTTON_3) ; 

dissociate (M0USE_BUTT0N_1, IC_LOCATOR, LID_LOC); 
dissociate (MOUSE_BUTTON_2, IC_LOCATOR, LID_LOC) ; 
dissociate (MOUSE_BUTTON_3, IC_LOCATOR, LID_LOC); 
dissociate (MOUSE_MOVE, IC_LOCATOR, LID_LOC) ; 

release_input_device (IC_LOCATOR, LID_LOC) ; /* shut down locator */ 

close_vws (name) ; 
close_cgi () ; 

} 

y / 



Request Input Cerror request_input (devclass, devnum, timeout, 

valid, sample, trigger) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint timeout; /* amount of time to wait for input */ 

Cawresult *valid; /* device status */ 

Cinrep * sample; /* device value */ 

Cint *trigger; /* trigger number */ 

request_input ( ) waits timeout microseconds for activation of a trigger 
associated with a specific device. If timeout is negative, the request will wait for- 
ever. request_input ( ) puts the input device in the RESPOND_EVENT 
state. If a trigger is activated within this period, the activating trigger and the 
device measure are returned in the trigger and sample arguments. If the trigger is 
not activated within this period, the current device measure is returned in the 
sample argument, and trigger is set to zero. Before returning, the input device is 
reset to NO_EVENTS state. 

request_input ( ) returns a device status in the argument This argu- 
ment uses the enumerated type Cawresult (AWait Result), which contains 
values describing the state of an input device. 

typedef enum { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE, 

NOT_SUPPORTED 
} Cawresult; 
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VALE)_DATA indicates that a trigger is activated within the specified timeout 
period. TIMED_OUT indicates that a trigger was not activated with a specified 
period. DISABLED indicates that a trigger is not activated. WRONG_STATE 
indicates SunCGI is not in state VSAC. NOT_SUPPORTED indicates the 
requested device is not a legal device. 

If the appropriate field of the sample argument is a pointer, it must be set to an 
application program allocated area. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

EINEVNEN [94] Events not enabled. 

5.3. Asynchronous Input This section explains the asynchronous method of input device management 

where the application process and the input device process operate simultane- 
ously. The designated input device is sampled with initiate_r ©quest ( ) 
and the measure of the input device is read with 

get_last_requested_input ( ) . Alternatively, the current measure of a 
device may be read with sample_input ( ) . 

Initiate Request Cerror initiate_request (devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

ini ti at e_r ©quest ( ) sets up a device so that the measure resulting from 
the next trigger activation will be placed in the request register, 
ini t i at e_r ©quest { ) puts the device in the REQUEST_EVENT state. It 
then returns to the calling function without waiting for a trigger activation. The 
value caused by the trigger activation can be obtained by the 
get_last_r©quested_input () function. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

EINNTASD [85] No triggers associated with device. 

5.4. Event Queue Input The event queue is a single FIFO buffer that holds events from input devices. 

Since the event queue has a fixed length, it must be processed in a timely fashion 
or it wiU overflow. Events can be removed from the event queue in three ways: 
the event at the head of the event queue can be processed with 
await_event ( } ; the entire event queue can be emptied with 
f lush_event_queue ( ) ; and the events from a particular device can be 
removed from the event queue with 
selective_f lush_of_event_qu©u© ( ) . 
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The following example program illustrates how to use the event queue input 
functions to get information from an input device. First, an IC_STRING device is 
initialized and associated with a trigger (the keyboard). The tracking method for 
the IC_STRING is defined to be a string that echos the keyboard input on the bot- 
tom of the viewport. The IC_STRING is put into the QUEUE_EVENT state with 
enable_event s { ) . After the trigger fires, the measure of the 1C_STRING 
device is determined with await_event ( ) . Finally, the IC_STRING is disso- 
ciated from the keyboard and released. The program then exits. 

/* NOTE: This example should be run from a grfxtool. */ 

#include <cgidefs.h> 

fdefine TEN_SECONDS (10 * 1000 * 1000) 

main ( ) 

{ 

Cint name; 

Cvwsurf device; 

Cawresult valid; 

Ccoor point; 

Cdevoff devclass = IC_STRING; 

Ceqflow overflow; 

Cinrep lvalue; 

Cint devnum = 1, 

replost , 
time_stamp, 

timeout = TEN_SECONDS, 
tracktype = 2 , 
trigger = 1; 

Cmesstype message_link; 

Cqtype qstat; 

NORMAL_VWSURF ( device, PIXWINDD) ; 
point. X = point. y = 16384; 
lvalue. xypt = &point; 

lvalue . string = "Return from await_event"; 
open_cgi ( ) ; 

open_vws ( &name, Sdevice) ; 

initialize_lid ( devclass, devnum, &ivalue) ; 
associate ( trigger, devclass, devnum); 

track_on( devclass, devnum, tracktype, (Ccoorpair *)0, &ivalue) ; 
enable_events ( devclass, devnum); 

await_event ( timeout, Svalid, Sdevclass, &devnum, sivalue, 

&message_link, &replost, &time_stamp, &qstat, Soverflow) ; 
printf ( "%s0, lvalue . string) ; 
disable_events ( IC_STRING, devnum) ; 
dissociate ( trigger, IC_STRING, devnum); 
release_input_device ( IC_STRING, devnum) ; 
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f — 


close vws ( name); 


\ 




close_cgi { ) ; 




} 






1 




J 



Enable Events 



Await Event 



Cerror enable_events (devclass , devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

enable_event s ( ) allows a device in NO_EVENTS state to put events on the 
event queue. enable_event s ( ) puts the input device in the QUEUE_EVENT 
state. An error is generated if the device specified by devclass or devnum does 
not exist or is not initialized. 



ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 
EIAEVNEN [93] 



CGI not in proper state: CGI should be in state VS AC. 
Input device does not exist. 

Input device not initialized. 

Events already enabled. 



Cerror await_event (timeout, valid, devclass, devnum, 
measure, message_link, replost, time_stamp, 
qstat, overflow) 



Cint timeout; 


/* 


input timeout period */ 


Cawresult *valid; 


/* 


status */ 


Cdevoff * devclass; 


/* 


device type */ 


Cint *devnum; 


/* 


device number */ 


Cinrep *measure; 


/* 


device value */ 


Cmesstype *message_link; 


/* 


type of message */ 


Cint *replost; 


/* 


reports lost */ 


Cint *time_stamp; 


/* 


t ime_s t amp * / 


Cqtype *qstat; 


/* 


queue status */ 


Ceqflow *overflow; 


/* 


event queue status */ 



await_event ( ) processes the event at the head of the event queue, valid is 
set to WRONG_STATE if SunCGI is not in state VSAC. If the event queue is 
EMPTY, then await_event ( ) waits timeout microseconds for a trigger to be 
activated. If timeout is less than 0, SunCGI waits until a trigger is activated. 
valid is set to VALID_DATA if a trigger is activated within the specified timeout 
period and TIMED_OUT otherwise. 

If either the event queue is not empty or a trigger is activated, the class, number 
and value of the device generating the event are reported in the returned argu- 
ments devclass, devnum, and measure. If the appropriate field of the measure 
argument is a pointer, it must be set to an application program allocated area. 

If two events on the event queue have the same trigger but different values, the 
argument message link is assigned to SIMULTANEOUS_EVENT_FOLLOWS; oth- 
erwise the argument message link is set to SINGLE_EVENT. The enumerated 
type Cmesstype contains the following values. 
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Flush Event Queue 



Selective Flush of Event 
Queue 



typedef enum { 

S IMULTANEOUS_EVENT_FOLLOWS , 

SINGLE_EVENT 
} Cmesstype; 

The rep lost and time stamp arguments should be ignored and are always zero. 
The returned argument qstat reports the queue status after an event is removed 
from the head of the event queue. 

typedef enum { 

NOT_VALID, 

EMPTY, 

NON_EMPTY, 

ALMOST_FULL, 

FULL 
} Cqtype; 

qstat is set to EMPTY if the event queue has no pending events, qstat is set to 
NON_EMPTY if the event queue has events pending, but is not FULL or 
ALMOST_FULL. qstat is set to ALMOST_FULL if there is room for only one 
more event on the event queue, qstat is set to FULL if there is no room for more 
events on the event queue. 

The argument overflow indicates whether the event queue has overflowed or not. 
The enumerated type Ceqf low contains the following values: 

typedef enum { 

NO_OFLO, 

OFLO 

} Ceqf low; 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINQOVFL [97] Input queue has overflowed. 

Cerror f lush_event_queue { ) 

f lush_event_queue ( ) discards aU events in the event queue. The purpose 
of f lush_event_queue ( ) is to return the event queue to a stable state 
(NO_OFLO). f lush_event_queue ( ) does not affect the state of input dev- 
ices. This function should be used carefuUy to avoid throwing away mouse- 
ahead or type-ahead inputs. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

Cerror select ive_f lush_of_event_queue (devclass, devnum) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

select ive_flush_of_event_queue ( } discards all events in the event 
queue which were generated by a specified device. 

select ive_flush_of_event_queue ( ) does not affect the state of the 
specified input device, devclass and devnum must refer to an existing and 
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initialized device or an error is produced. However, no error is returned if no 
events from the specified device are pending. 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. 

EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

5.5. Miscellaneous Input The functions described in this section can be used with several of the input dev- 
Functions ice management techniques described in the previous sections. For example, 

sample_input ( ) can be used when a device is in either REQUEST_EVENT or 
QUEUE_EVENT State. Likewise, disable_e vents ( ) can be used in either 
of these states. 

Sample Input Cerror sample_input (devclass, devnum, valid, sample) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device status */ 

Cinrep *sample; /* device value */ 

sample_input ( ) reports the current measure of the specified input device in 
the returned argument sample. The returned argument valid reports whether the 
device is initialized and prepared to receive an input. The current measure of the 
device may be set by a queued event, a requested event, or a device initialization 
depending on the state of the input device and the most recent trigger 
activation(s). See the introduction of this chapter for an explanation of the rela- 
tionship between the measure of an input device and the state of an input device. 
If the appropriate field of the sample argument is a pointer, it must be set to an 
application program allocated area. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

Get Last Requested Input Cerror get_last_requested_input (devclass, devnum, 

valid, sample) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device status */ 

Cinrep *sample; /* device value */ 

get_last_requested_input { ) returns the contents of the request regis- 
ter. get_last_requested_input { ) is usually used with 
initiate_request ( ) , but request_input ( ) also changes the contents 
of the request register. The returned argument valid indicates whether the device 
exists and is initialized. The returned argument sample reports the event in the 
request register. If no event is in the request register, the initial device value is 
reported. If the appropriate field of the sample argument is a pointer, it must be 
set to an application program allocated area. 
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ENOTVS AC [4] CGI not in proper state: CGI should be in state VS AC. 

EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

Disable Events Cerror disable_events (devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

disable_events { ) puts the input device in the NO_EVENTS state. If the 
device is in RESPOND_EVENT state, the specified device is returned to 
NO_EVENTS state; the measure of the device is not changed by 
disable_events { ) . If the device is in QUEUE_EVENT state, 
disable_events ( ) stops the specified device from putting events on the 
event queue. However, existing entries on the event queue are not removed and 
existing associations remain, devclass and devnum must refer to an existing and 
initialized device or an error is produced. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
EINDNOEX [80] Input device does not exist. 

EINDINIT [81] Input device not initialized. 

EINEVNEN [94] Events not enabled. 

5.6. Status Inquiries The current state of the input devices, triggers, and the event queue can be 

obtained by using the functions discussed in this section. 

Inquire LID State List Cerror inquire_lid_state_list (devclass, devnum, 

valid, list) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device supported at all */ 

Cstatelist *list; /* table of descriptors */ 

inquire_lid_state_list ( ) reports the status of a specific input device 
specified by devclass and devnum. The argument valid reports whether the dev- 
ice is supported at all. The list argument reports the track, associations, state, 
and measure of the device in the appropriate elements of list. When checking the 
elements of list, first check the state element — if state is RELEASED, the other 
elements of list are undefined. 

typedef struct { 

Clidstate state; 

Cpromstate prompt; 

Cackstate acknowledgement; 

Cinrep *current; 

Cint n; 

Cint *triggers; 

Cechotype echotyp; 

Cechostate echosta; 

Cint echodat; 

} Cstatelist; 
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ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 

EINDNOEX [80] Input device does not exist. 

Inquire LID State Cerror inquire_lid_state (devclass, devmim, valid, state) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device supported at all */ 

Clidstate *state; /* table of descriptors */ 

inquire_lid_state ( ) reports the status of a specific input device specified 
by devclass and devnum. The argument valid reports whether the device is sup- 
ported at all. The state argument (of type Clidstate) reports the current state 
of the specified input device. 

typedef enum { 

RELEASE, 

NO_EVENTS, 

REQUE S T_E VENT , 

RE S P OND_E VENT , 

QUEUE_EVENT 
} Clidstate; 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 

EINDNOEX [80] Input device does not exist 

Inquire Trigger State Cerror inquire_trigger_state (trigger, valid, list) 

Cint trigger; /* trigger number */ 

Clogical *valid; /* trigger state */ 

Ctrigstate *list; /* trigger description table */ 

inquire_tr igger_state ( ) describes the binding between a trigger and an 
input device. If the state element of the returned argument list is INACTIVE, no 
associations have been made with the trigger. An error is generated if the trigger 
does not exist. 

typedef struct { 

Cactstate state; /* state */ 

Cassoclid *assoc; /* list of associations */ 

} Ctrigstate; 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 

E INTRNEX [86] Trigger does not exist. 

Inquire Event Queue State Cerror inquire_event_queue_state (qstat, qflow) 

Cqtype * qstat; /* queue state */ 

Ceqflow * qflow; /* overflow indicator */ 

inquir e_event_queue_state { ) reports the status of the event queue. 
qstat indicates whether any events are pending. The argument qflow reports if 
the event queue is overflowing. 
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typedef enum { 

NOT_VALID, 

EMPTY, 

NON_EMPTY, 

ALMOST_FULL, 

FULL 

} Cqtype; 

typedef enum { 

NO_OFLO, 

OFLO 

} Ceqflow; 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC. 
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Unsupported Aspects of CGI 



SunCGl does not support certain optional aspects of the 1984 draft ANSI CGI 
standard. (This draft may greatly differ from other drafts of CGI.) Most notably 
SunCGl does not support the fuU constellation of negotiation functions or track- 
ing. SunCGI does not allow the resetting of coordinate type, coordinate preci- 
sion or color specification mode because to do so would greatly reduce the speed 
of application programs written in SunCGl. Furthermore, SunCGl does not sup- 
port echoing functions for input, but provides the tracking functions instead. 

T able A- 1 U nsupported Control Functions 

Function 

vdc_type ( ) 

vdc_precision_f or_integer_points ( ) 
vdc_precision_f or_real_points ( ) 
integer_precision ( ) 
real_jprecision { ) 
index_precision ( ) 
color_selection_mode () 
color_precision ( ) 
color_index_precision ( ) 
viewport_specif ication_mode ( ) 
make_picture_current () 



Table A-2 U nsupported Input Functions 

Function 

set_prompt_state () 
set_acknowledgement_state () 
echo_on ( ) 
echo_of f ( ) 
echo_update { ) 
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The following SunCGI functions are nonstandard (that is, are not in the standards 
document) and are included to make CGI easier to use. hi addition, SunCGI has 
non-standard view surface arguments for certain control functions. 

Table A-3 Nonstandard Control Functions 

Function 

open_cgi {) 
open_vws ( ) 
activate_vws () 
deactivate_vws {) 
close_vws { ) 
close_cgi ( ) 



Table A-4 Nonstandard Attribute Functions 

Function 

def ine_bundle_index ( ) 
line_endstyle ( ) 
set_global_drawing_mode () 
pattern_with_f ill_color {) 
fixed font () 



The Cinrep structure contains a presently unsupported pick field, for compati- 
bility with future segment manipulation capabilities. 
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Type and Structure Definitions 



This appendix provides a list of the structures and enumerated types used by 
SunCGI functions. In addition, a list of useful constants defined in 
<cgiconstants .h> is given. 





/* devices */ 



#def ine 


BWIDD 


1 








#def ine 


BW2DD 


2 








#def ine 


CGIDD 


3 








#def ine 


BWPIXWINDD 


4 








#def ine 


CGPIXWINDD 


5 








#def ine 


GPIDD 


6 








#def ine 


CG2DD 


7 








♦define 


CG4DD 


8 








♦define 


PIXWINDD 


9 








♦define 


VWSURF_NEWFLG 1 








♦define 


MAXVWS 


5 








♦define 


MAXTRIG 


6 








♦define 


MAXASSOC 


5 


/* 


maximum 


associations for a device */ 


♦define 


MAXE VENTS 


1024 


/* 


maximum 


number of events the buffer holds */ 


/* limits */ 










♦define 


MAXAESSIZE 


10 


/* 


maximum 


number of AES table entries */ 


♦define 


MAXNUMPATS 


50 


/* 


maximum 


number of pattern table entries */ 


♦define 


MAXPATSIZE 


256 


/* 


maximum 


pattern size */ 


♦define 


MAXPTS 


1024 


/* 


maximum 


number of pts per polygon */ 


♦define 


MAXCHAR 


256 


/* 


maximum 


number of chars in a string */ 


♦define 


OUTFUNS 


67 


/* 


number of output functions */ 


♦define 


INFUNS 


22 


/* 


number of input functions */ 


♦define 


DEVNAMESIZE 


20 
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The type and stmcture definitions that follow can be found in the header file 
<cgidef s .h>. 

typedef enum { 

ACK_ON, 

ACK_OFF 
} Cackstate; 

typedef emxm { 

ACTIVE, 

INACTIVE 
} Cact state; 

typedef enum { 

CLEAR, 

NO_OP, 

RETAIN 
} Cacttype; 

typedef enum { 

INDIVIDUAL, 

BUNDLED 
} Casptype; 

typedef struct { 

Cint n; 

Cdevoff *class; 

Cint *assoc; 

} Cassoclid; 

typedef enum { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE, 

NOT_SUPPORTED 
} Cawresult; 

typedef enum { 

BITNOT, 

BITTRUE 
} Cbitmaptype ; 

typedef enum { 

TRANSPARENT, 

OPAQUE 
} Cbmode ; 
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typedef struct { 





Clintype 


line_type; 




Cf loat 


line width; 




Cint 


line_color ; 




Cmartype 


marker type; 




Cf loat 


marker size; 




Cint 


marker_color ; 




Cintertype interior_style; 




Cint 


hat ch_index ; 




Cint 


pattern index; 




Cint 


f ill_color ; 




Clintype 


perimeter type; 




Cf loat 


perimeter width; 




Cint 


perimeter color; 




Cint 


text_f ont ; 




Cprectype 


text_precision; 




Cf loat 


character expansion 




Cf loat 


character spacing; 




Cint 


text_color ; 


} 


Cbunatt ; 




typedef struct { 




unsigned 


char *ra; 




unsigned 


char *ga; 




unsigned 


char *ba; 




Cint 


n; 


} 


Ccentry; 




typedef enum 


{ 




OPEN, 






CLOSE 




} 


Ccf lag; 




typedef struct { 




Cint 


numloc; 




Cint 


numval; 




Cint 


numstrk; 




Cint 


numchoice; 




Cint 


numstr; 




Cint 


numtrig; 




Csuptype 


event_queue ; 




C sup type 


asynch; 




Csuptype 


coord_map; 




Csuptype 


echo; 




Csuptype 


tracking; 




Csuptype 


prompt ; 




Csuptype 


acknowledgement ; 




Csuptype 


trigger manipulation; 



} Ccgidesctab; 
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typedef enum { 

YES, 

NO 

} Cchangetype; 

typedef char Cchar; 

typedef enum { 
NOCLIP, 

CLIP, 

CLIP_RECTANGLE 
} Cclip; 

typedef enum { 
CHORD, 

PIE 

} Cclosetype; 

typedef enum { 
REPLACE, 

AND, 

OR, 

NOT, 

XOR 

} Ccombtype; 

typedef struct { 
Cint x; 

Cint y; 

} Ccoor; 

typedef struct { 

Ccoor *ptlist; 
Cint n; 

} Ccoorlist; 

typedef struct { 
Ccoor *upper; 
Ccoor *lower; 

} Ccoorpair; 

typedef enum { 
IC_LOCATOR, 
IC_STROKE, 
IC_VALUATOR, 
IC_CHOICE, 
IC_STRING, 
IC_PICK 
} Cdevoff; 
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typedef enum { 

E_TRACK, 

E_ECHO, 

E_TRACK_OR_ECHO , 
E_TRACK_AND_ECHO 
} Cechoav; 

typedef struct { 

Cinrep *echos; 

Cint n; 

} Cechodatalst ; 

typedef enum { 

ECHO_OFF, 

ECHO_ON, 

TRACK_ON 
} Cechostate; 

typedef struct { 

Cechostate *echos; 
Cint n; 

} Cechostatelst ; 

typedef enum { 

NO_ECHO, 

PRINTERS_FIST, 

HIGHLIGHT, 

RUBBER_BAND_BOX , 

DOTTED_LINE, 

SOLID_LINE, 

STRING_ECHO, 

XLINE, 

YLINE 

} Cechotype; 

typedef struct { 

Cint n; 

Cechoav *elements; 

Cechotype *echos; 

} Cechotypelst ; 

typedef enum { 

NATURAL, 

POINT, 

BEST_FIT 
} Cendstyle; 

typedef enum { 

NO_OFLO, 

OFLO 

} Ceqflow; 
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typedef Cint Cerror; 

typedef enum { 
INTERRUPT, 
NO_ACTION, 

POLL 

} Cerrtype; 

typedef enum { 
CLIP_RECT, 
VIEWPORT, 
VIEWSURFACE 

} Cexttype; 

typedef struct 
Cintertype 
Cf lag 
Cint 
Cint 
Cint 
Cint 

Clintype 
Cf loat 
Cint 

} Cfillatt; 

typedef enum { 

OFF, 

ON 

} Cflag; 

typedef struct { 

Cint n; 

Cint *num; 

Casptype * value; 

} Cflaglist; 

typedef float Cfloat; 

typedef enum { 

FREEZE , 

REMOVE 

} Cfreeze; 

typedef enum { 

LFT, 

CNTER, 

RGHT, 

NRMAL, 

CNT 

} Chaligntype; 



style; 

visible; 

color; 

hat ch_index ; 

pattern_index ; 

index; 

pstyle; 

pwidth; 

pcolor; 
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typedef enum { 

NO_INPUT, 

ALWAYS_ON, 

SETTABLE, 

DEPENDS_ON_LID 
} Cinputability; 

typedef struct { 

Ccoor *xypt; 

Ccoorlist *points; 

Cfloat val; 

Cint choice; 

Cchar *string; 

Cpick *pick; 

} Cinrep; 

typedef int Cint; 

typedef enum { 

HOLLOW, 

SOLIDI, 

PATTERN, 

HATCH 

} Cintertype; 

typedef struct { 

Clogical sample; 

Cchangetype change ; 

Cint numassoc; 

Cint *trigassoc; 

Cinputability prompt; 

Cinputability acknowledgement; 
Cechotypelst *echo; 

Cchar *classdep; 

Cstatelist state; 

} Cliddescript ; 

typedef enum { 

RELEASE, 

NO_E VENTS, 

REQUEST_EVENT, 

RESPOND_EVENT, 

QUEUE_EVENT 
} Clidstate; 

typedef struct { 

Clint ype style; 

Cfloat width; 

Cint color; 

Cint index; 

} Clinatt; 
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typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 

DASH_DOT_DOTTED, 

LONG_DASHED 
} Clint ype; 

typedef enum { 

L_FALSE, 

L_TRUE 
} Clogical; 

typedef struct { 

Cma r t ype t ype ; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

typedef enum { 

DOT, 

PLUS, 

ASTERISK, 

CIRCLE, 

X 

} Cma r t ype; 

typedef enum { 

S IMULTANEOUS_EVENT_FOLLOWS , 
SINGLE_EVENT 
} Cmesstype; 

typedef enum { 

RIGHT, 

LEFT, 

UP, 

DOWN 

} Cpathtype; 
typedef struct { 



Cint 


cur index; 


Cint 


row; 


Cint 


column; 


Cint 


*colorlist ; 


Ccoor 


*point ; 


Cint 


dx; 


Cint 


dy; 



} Cpatternatt; 
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typedef struct { 
int segid; 
int pickid; 

} Cpick; 

typedef struct pixrect Cpixrect; 

typedef enum { 

STRING, 

CHARACTER, 

STROKE 

} Cprectype; 

typedef enum { 

PROMPT_OFF, 

PROMPT_ON 

} Cpromstate; 

typedef enum { 

NOT_VALID, 

EMPTY, 

NON_EMPTY, 

ALMOST_FULL, 

FULL 

} Cqtype ; 

typedef enum { 

ABSOLUTE, 

SCALED 

} Cspecmode ; 

typedef struct 
Clidstate 
Cpromstate 
Cackstate 
Cinrep 
Cint 
Cint 

Cechotype 
Cechostate 
Cint 

} Cstatelist; 

typedef enum { 

NONE, 

REQUIRED_FUNCT IONS_ONLY, 
SOME_NON_REQUIRED_FUNCT IONS , 
ALL_NON_REQUIRED_FUNCT IONS 

} C sup type; 



{ 

state; 
prompt ; 

acknowledgement ; 
*current ; 
n; 

* t riggers ; 
echotyp; 
echosta; 
echodat ; 
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typedef struct { 



Cint 


font set ; 


Cint 


index; 


Cint 


current_f ont ; 


Cprectype 


precision; 


Cf loat 


exp factor; 


Cf loat 


space; 


Cint 


color; 


Cint 


height; 


Cf loat 


basex; 


Cf loat 


basey; 


Cf loat 


upx; 


Cf loat 


upy; 


Cpathtype 


path; 


Chaligntype 


halign; 


Cvaligntype 


valign; 


Cf loat 


hcalind; 


Cf loat 


vcalind; 


} Ctextatt; 




typedef enum { 




NOT_FINAL, 




FINAL 




} Ctextfinal; 




typedef struct { 




Cchangetype 


change ; 


Cassoclid 


*numassoc; 


Cint 


maxassoc; 


Cpromstate 


prompt ; 


Cackstate 


acknowledgement 


Cchar 


*name; 


Cchar 


description; 


} Ctrigdis; 




typedef struct { 




Cactstate state; 


Cassoclid * 


assoc; 


} Ctrigstate; 




typedef enum { 




TOP, 




CAP, 




HALF, 




BASE, 




BOTTOM, 




NORMAL, 




CONT 





} Cvaligntype; 
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typedef enum { 
INTEGER, 
REAL, 

BOTH 

} Cvdctype; 
typedef struct { 



Cchar 


screenname [DEVNAMESIZE] ; 


Cchar 


windowname [DEVNAMESIZE] ; 


Cint 


windowfd; 


Cint 


retained; 


Cint 


dd; 


Cint 


cmapsize; 


Cchar 


cmapname [DEVNAMESIZE] ; 


Cint 


flags; 


Cchar 


**ptr; 



} Cvwsurf; 
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Error Messages 



This appendix lists the error messages in numerical order. The probable cause of 
each error is given in the sentences following the error. In addition to explaining 
the error message, an initial suggestion for corrective action is given. In the title 
for each group of errors, the range of error numbers is given in parentheses after 
the title. If your application program is not behaving as you want it to, but does 
not generate error messages, then the tables at the end of this appendix, which 
lists commonly encountered problems and frequent causes, may be helpful. 

C.l. Successful Return (0) no_error [0] No error. 

C.2. State Errors (1-5) ENOTCGCL [ 1] CGI not in proper state: CGI should be in state CGCL. A 

call to open_cgi ( ) was attempted when cgi was already 
open. Elimination of the error can be accomplished by 
removing the offending call to open_cgi ( ) . 

ENOTCGOP [2] CGI not in proper state: CGI should be in state CGOP. 

Every function except open_cgi ( ) requires that CGI be 
open. If this error is received, make sure that your applica- 
tion program has called open cgi ( ) , or that it has not 
recently called close_cgi ( ) . 

ENOTVSOP [3] CGI not in proper state: CGI should be in state VSOP. 

The function which generated the error requires that at 
least one view surface be open. Corrective action would 
include either removing the most recent caU to 
close_vws 0 or by including a call to open_vws ( ) . 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VS AC. 

The function which generated the error requires that at 
least one view surface be active. Corrective action would 
include either removing the most recent caU to 
deact ivat e_vws ( ) or by including a call to 
activate_vws () . 
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ENOTOPOP [5] 



C.3. Control Errors (10-16) evsidinv[10] 



ENOWSTYP [11] 



EMAXVSOP [12] 



EVSNOTOP [13] 



E VS IS ACT [14] 



EVSNTACT [15] 



EINQALTL [16] 



C.4. Coordinate Definition ebadrctd [20] 
(20-24) 




CGI not in proper state: CGI should be in state CGOP, 
VSOP, or VSAC. The function which generated the error 
requires that SunCGI is at least initialized. If this error is 
received, make sure that your application program has 
called open_cgi ( ) , or that it has not recently called 
close_cgi ( ) . 

Specified view surface name is invalid. The view surface 
name specified by the name argument has never been 
opened or if it has been opened, it has since been closed. 
Corrective action involves opening the view surface or 
changing the value of the name argument. 

Specified view surface type does not exist. The application 
program has specified a type of view surface which is not 
supported by SunCGI. Corrective action involves chang- 
ing the type of view surface. 

Maximum number of view surfaces already open. An 
attempt was made to open a view surface when the max- 
imum number of view surfaces is already open. Corrective 
action involves removing one call to open_vws ( ) . 

Specified view surface not open. An attempt was made to 
close a view surface which is already closed. Corrective 
action involves removing one call to close_vws ( ) . 

Specified view surface is active. An attempt was made to 
activate a view surface which is already activated. Correc- 
tive action involves removing one call to 
activate_vws ( ) . 

Specified view surface is not active. An attempt was made 
to deactivate a view surface which has already been deac- 
tivated. Corrective action involves removing one call to 
deactivate_vws () . 

Inquiry arguments are longer than list. A call to an 
inquiry negotiation function with indices greater than the 
number of supported functions was made. The returned 
list is always empty. Corrective action may be facilitated 
by obtaining the size of the list by using the 
inquire_device_class 0 function. 

Rectangle definition is invalid. The application program 
has made a caU to vdc_extent ( ) or 
device_viewport ( ) with the coordinates of both 
comers equal in the x or y dimensions or both. Corrective 
action involves changing one of the arguments to the func- 
tion which generated the error so that the values of the two 
arguments are different in both the x and y dimensions. 
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EBDVIEWP [21] 


Viewport is not within Device Coordinates. A call to 
device_viewport ( ) has been made which specifies a 
viewport larger than the view surface. Corrective action 
involves making the arguments to 
device viewport ( ) less than the view surface size. 
The size of the view surface can be obtained by calling the 
inquire_physical_coordinate_system ( ) 
function. 




ECLIPTOL [22] 


Clipping rectangle is too large. The clipping rectangle 
would exceed the boundaries of VDC space. Corrective 
action involves resetting the clipping rectangle to be 
within the limits of VDC space. 




ECLIPTOS [23] 


Clipping rectangle is too small. The clipping rectangle 
would define an area of screen space smaller than one 
pixel. The clipping rectangle remains unchanged. Since 
the occurrence of this error is partially a function of the 
size of the view surface, changing the size of the view sur- 
face may be a viable alternative to changing the size of the 
clipping rectangle. 




EVDCSDIL [24] 


VDC space definition is illegal. One or more of the argu- 
ments to the vdc_extent ( ) fimction exceeds the 
acceptable limits (-32767 to 32767) or the coordinates of 
the lower-left hand comer are greater than the coordinates 
of the upper-right hand comer. Corrective action involves 
changing the arguments to vdc_extent ( ) . 


C.5. Output Attributes 
(30-51) 


EBTBUNDL [30] 


ASF is BUNDLED. Error 30 is generated when attempting 
to call an individual attribute function when the attributes 
are specified by entries in the attribute table. Calls to 
these functions have no effect on the current attributes. 
Corrective action includes resetting the attribute selector 
to BUNDLED by using the attribute selector functions. 




EBBDTBDI [31] 


Bundle table index out of range. The entry in the bundle 
table exceeds the size of the table. The only corrective 
action is to change the value of the index argument. 




EBTUNDEF [32] 


Bundle table index is undefined. The entry in the attribute 
table specified by the most recent call to an attribute table 
index setting function has not been defined by SunCGI or 
the application program. 




EBADLINX [33] 


Polyline index is invalid. The polyline bundle is not 
defined. Corrective action involves changing the index 
argument to polyline bundle index (), or by 
defining the polyline bundle index. 
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EBDWIDTH [34] 



ECINDXLZ [35] 



EBADCOLX [36] 



EBADMRKX [37] 



EBADSIZE [38] 



EBADFABX [39] 



EPATARTL [40] 



EPATSZTS [41] 



ESTYLLEZ [42] 



Width must be nonnegative. The width of a perimeter or 
line must be greater than or equal to zero. The current 
value of the perimeter width or line width remains 
unchanged. Changing the value of the width argument to a 
nonnegative value will correct this error. 

Color index is less than zero. The value of the index argu- 
ment to one of the attribute functions or the color entry in 
one of the bundles is negative. Corrective action involves 
changing the value of the color. 

Color index is invalid. The color index argument to one of 
the attribute functions or the color entry in one of the bun- 
dles is not defined in the colormap. Indices in the color 
lookup table must be between 0 and 255 for the Sun 8-bit 
per pixel frame buffer. Any color specification outside of 
this range is ignored. Corrective action involves changing 
the value of the color. 

Polymarker index is invalid. The polymarker bundle is not 
defined. Corrective action involves changing the index 
argument to polymarker_bundle_index ( ) , or by 
defining the polymarker bundle index. 

Size must be nonnegative. The size of a marker or line 
must be greater than or equal to zero. The current value of 
the marker size remains unchanged. Changing the value of 
the size argument to a nonnegative value will correct this 
error. 

Fill area index is invalid. The fill area bundle is not 
defined. Corrective action involves changing the index 
argument to f ill_area_bundle_index ( ) , or by 
defining the fill area bundle index. 

Pattern array too large. The pattern array must contain 
less than 257 elements. The pattern is not entered into the 
pattern table. Corrective action involves designing a new 
pattern. 

Pattern size too small. The pattern size must be at least 
two-by-two. The pattern is not entered into the pattern 
table. Corrective action could include designing a new 
pattern which includes several replications of the original 
pattern. 

Style (pattern or hatch) index is less than zero. All indices 
in the pattern table must be positive. To fix this mistake, 
change the argument to the pattern_index ( ) or the 
hatch index ( ) or the entries in the bundle table. 
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ENOPATNX [43] 



EPATITOL [44] 



EBADTXTX [45] 



EBDCHRIX [46] 



ETXTFLIN [47] 



ECEXFOOR [48] 



ECHHTLEZ [49] 



ECHRUPVZ [50] 



ECOLRNGE [51] 



Pattern table index not defined. The argument to the 
hatch_index ( ) orpattern_index ( ) function or 
the entry bundle table should be reset to correspond to a 
defined value. 

Pattern table index too large. The index argument to 
pattern_table { ) exceeded the bounds of the pattern 
table. The pattern is not entered into the pattern table. 
Redefining the pattern index to be between one and ten 
will eliminate the error. 

Text index is invalid. The text bundle is not defined. 
Corrective action involves changing die index argument to 
text bundle index ( ) , or by defining the text bundle 
index. 

Character index is undefined. CGI ignores all character 
indices other than index 1. You are advised to ignore the 
character_set_index ( ) fimction entirely. 

Text font is invalid. The text fonts range from 1 to 6. All 
other integers do not correspond to actual fonts. Correc- 
tive action involves changing the argument to the 
text_f ont_index ( ) function or resetting the font 
index in the text Imndle. 

Expansion factor is out (grange. The character expansion 
factor or the character space ejq>ansion factor would 
result in a character or a space which would exceed the 
bounds of the screen or would result in a character smaller 
than the limitations of the character drawing software. To 
eliminate this error, reset the offending value to within an 
acceptable range (0.1 -2.0 are reasonable guidelines). 

Character height is less than or equal to zero. The char- 
acter height must be positive. Corrective action involves 
changing the argument to the character height function or 
the element of the text bundle. 

Length of character up vector or character base vector is 
zero. Both the character up vector and the character base 
vector must be nonzero. Corrective action involves chang- 
ing the arguments to the 

character_or ientation { ) function or the element 
of the text bundle. 

RGB values must be between 0 and 255. The red, green, 
and blue values are only defined between 0 and 255. The 
call to color table ( ) that produced the error is 
ignored. Corrective action requires respecifying the values 
of the arguments to color table ( ) . 
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C.6. Output Primitives 
(60-70) 



ENMPTSTL [60] 



EPLMTWPT [61] 



EPGMTHPT [62] 



EGPLISFL [63] 



EARCPNCI [64] 



EARCPNEL [65] 



ECELLATS [66] 



ECELLPOS [67] 



ECELLTLS [68] 



Number of points is too large. The number of points 
exceeds MAXPTS. Change the n element of the Ccoor- 
list structure to a value less than or equal to MAXPTS. 

polylines must have at least two points. Change the n ele- 
ment of die Ccoor list structure to a value greater than 
or equal to 2 and add the corresponding points to the ptlist 
element. 

Polygons must have at least three points. Change the n 
element of the Ccoorlist structure to a value greater 
than or equal to 3 and add the corresponding points to the 
ptlist element. 

Global polygon list is full. The number of points on the 
global polygon list exceeds MAXPTS. The points which 
exceed MAXPTS are ignored. This error can be corrected 
by inserting a call to polygon ( ) (which clears the glo- 
bal polygon list by displaying its contents) before the call 
to partial_polygon ( ) that caused the overflow. 

Arc points do not lie on circle. The starting and ending 
points of either an open or close circular arc do not lie on 
the perimeter of the circle described by the arguments cl 
and rad. If this error occurs, the arc is not drawn. Correc- 
tive action may include determination of the endpoints 
with tl.e application program (for example c2.x = 
rad* cos(start angle);). 

Arc points do not lie on ellipse. The starting and ending 
points of either an open or close elliptical arc do not lie on 
the perimeter of the ellipse described by the arguments cl, 
c2, and c3. If this error occurs, the arc is not drawn. 
Corrective action may include determination of the end- 
points with the application program. 

Distance between p and q too small for given dx, dy. The 
dimensions of the cell array are too small for a cell array 
element to be mapped onto one pixel of the view surface. 
The ceU array is not drawn. This error depends on the 
physical size of the view surface as well as the limits of 
VDC space. Therefore, corrective action might require 
changing the size of the view surface, VDC space, or both. 

Cell array dimensions must be positive. Negative ceU 
array dimensions are not permitted. Corrective action 
requires changing the parameters to the cell array func- 
tion. 

Is not used. 
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EVALOVWS [69] 


Value outside of view surface. A coordinate of a pixel 
array is outside the physical range of the view surface. 

The pixel array is not drawn. Change the arguments to the 
pixel array () orbitblt source array (). 




EPXNOTCR [70] 


Pixrect not created. One of the bitblt functions required a 
user-defined pixrect, and that pixrect had not been created. 
Corrective action involves creating a pixrect in your appli- 
cation program before calling the offending bitblt function. 


C.7. Input (80-97) 


EINDNOEX [80] 


Input device does not exist. The input device specification 
(specified by the devclass and devnum arguments of most 
input functions) does not exist. Corrective action involves 
resetting the device specification to a valid device. 




EINDINIT [81] 


Input device not initialized. A call to an input device func- 
tion specified a device that was not initialized. Calls 
which generate this error have no effect. A call to 
initializ e_l i d ( ) should be inserted before the call 
generating the error. 




EINDALIN [82] 


Input device already initialized. An attempt was made to 
initialize a device that has previously been initialized. The 
parameters to the offending call to initialize lid ( ) 
are ignored. Removing the offending call to 
initialize_lid ( ) will correct this error. 




EINASAEX [83] 


Association already exists. An attempt is being made to 
bind the input device to a trigger to which it has been pre- 
viously bound. The status of the input device trigger are 
unchanged. This error is purely informational and no 
corrective action is required. 




EINAIIMP [84] 


Association is impossible. An attempt is being made to 
bind the input device to a trigger to which it cannot be 
bound. For example, an IC_STRING device cannot be 
bound to a mouse button. To eliminate this error, change 
the arguments to the offending call of the as so elate ( ) 
function. 




EINNTASD [85] 


Association does not exist. An attempt to call an input 
function that specifies a device with no associated triggers 
was made. The offending call is ignored. Corrective 
action involves calling associate (} before the offend- 
ing caU is issued. 




EINTRNEX [86] 


Trigger does not exist. An attempt was made to associate 
or inquire about a trigger which has a number less than one 
or greater than five. The offending call is ignored. To 
eliminate the error, change the trigger number. 
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EINNECHO [87] 



EINECHON [88] 



EINEINCP [89] 



EINERVWS [90] 



EINETNSU [91] 



EINENOTO [92] 



EIAEVNEN [93] 



EINEVNEN [94] 



EBADDATA [95] 



Input device does not echo. CHOICE devices can only 
echo if one echos the LOCATOR device. Create and use 
the device as a CHOICE device, but for the tr ack_on ( } 
function call, pass the device argument as a LOCATOR 
device, even though it is a CHOICE device. 

Echo already on. A call to tr ack_on ( ) has been made 
to a device whose echoing ability has already been 
activated. To stop generation of the error either remove 
the offending call or change the arguments to specify a 
device whose echo is currently off. 

Echo incompatible with existing echos. Although SunCGI 
can support certain combinations of echos (such as 
IC_STRING and IC_LOCATOR), not all combinations are 
supported. The easiest remedy is to remove the offending 
call from the application program. 

Echo region larger than view surface. Error 90 is gen- 
erated when the rectangle defined by the echoregion argu- 
ment exceeds the limits of VDC space. To eliminate this 
error, change the values to the echoregion argument to be 
within the confines of VDC space. 

Echo type not supported. All devices except the 
IC_STROKE device only support one type of echo. There- 
fore, assigning a value to echotype other than zero or one 
will produce an error for any device except IC_STROKE. 
Corrective action involves changing the value of the echo- 
type argument. 

Echo not on. The device echoing has not been turned on. 
Either remove the call to t r ack_of f ( ) , turn the echo 
on, or change the device specification. 

Events already enabled. Events have already been enabled 
for the specified device. The solution is to remove the 
offending caU to enable_e vents ( ) . 

Events not enabled. Events have not been enabled for die 
specified device. The solution is to include a call to 
enable_event s ( ) before a call to the 
await_event ( ) , sample_input ( ) , or 
get_last_requested_input { ) function is made 
with the specified device as input parameter. 

Contents of input data record are invalid. The value argu- 
ment of initialize_lid ( ) function is out of range or 
is the wrong type. The solution is to change the contents 
of the value argument. 
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ESTRS I ZE [96] Length of initial string is greater than the implementation 
defined maximum. The initial string in the value argument 
is greater than 80 characters. Shorten the string. 

EINQOVFL [97] Input queue has overflowed. The event queue can no 

longer record input events. Solutions include flushing the 
event queue or dequeueing events with the 
await_€vent { ) , sample_input ( ) , or 
get_last_requested_input () function. 



C.8. Implementation ememspac [110] 

Dependent (110-112) 

ENOTCSTD [111] 
ENOTCCPW [112] 

C.9. Possible Causes of 
Visual Errors 



Space allocation has failed. A function that was supposed 
to work has failed. The only action which you can take is 
to eliminate other processes which may be using memory. 
If you have eliminated aU other processes, and this error is 
still generated, please contact Sun Microsystems. 

Function or argument not compatible with standard CGI. 
A function caU is not supported by the CGI library. 

Function or argument not compatible with CGIPW mode. 
A function call is not supported by the CGIPW library. 



Table C-1 Attribute Errors 



Behavior 


Possible Cause 


Attribute setting has no effect 


Attribute ASF is set to bundled. 


Text attributes have no effect 


Text precision is set to CHARAC- 
TER. 

Attribute ASF is set to BUNDLED. 


PATTERN fill is the same as 
HATCH 


pattern index and hatch index 

are identical. 

pattern size is too small. 


PATTERN fiU is different on dif- 
ferent view surfaces. 


View surfaces are of different 
size. 
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Table C-2 Input Errors 



Behavior 


Possible Cause 


Input device does not report 


Device not initialized. 


Input device does not echo 


Echo not initialized. 


Input device does not echo on 


Echo region not set to whole 


whole view surface 


view surface. 



Table C-3 View Surface Errors 



Behavior 


Possible Cause 


Segmentation fault for 


devdd argument for 


open_vws { ) 


open vws ( ) is declared as a 
pointer (the address of devdd 
should be passed). 


No primitives displayed 


View surface not initialized. 

View surface not active. 

VDC to device coordinate map- 
ping makes objects too small. 

Qipping rectangle is too smaU 
and clipping is ON. 

Perimeter visibility is set to OFF 
and interior style is set to HOL- 
LOW. 

line color or fill color is set to 
background color. 


Primitives displayed on 


Undesired view surfaces have 


undesired view surfaces 


not been deactivated. 


Segmentation fault for inquiry 


Passing variable instead of 


functions 


address ( & ) of variable. 
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Table C-4 Primitive Errors 



Behavior 


Possible Cause 


Polylines or polymaricers aren’t 
displayed. 


Width or size is zero. 

Color is the same as back- 
ground. 


Polygon borders aren’t 
displayed. 


Width is zero. 

Color is the same as back- 
ground. 

Perimeter visibility is set to OFF. 


Circles aren’t displayed. 


Width or size is zero. 




Color is the same as back- 
ground. 


Ellipses aren’t displayed. 


Width or size is zero. 




Color is the same as back- 
ground. 


Text isn’t displayed. 


Width or size is zero. 

Color is tile same as back- 
ground. 

Character height is too small. 

Coordinates are outside the 
range of VDC space or the clip- 
ping rectangle. 


Cell arrays aren’t displayed. 


dx or dy arguments are too 
small. 




Color is the same as back- 
ground. 


CeU arrays aren’t displayed on 
all active view surfaces. 


Mapping from cell size to view 
surface for smaller view sur- 
faces is too small. 


Pixel arrays aren’t displayed. 


Location is outside of view sur- 
face or clipping rectangle. 

Color is the same as back- 
ground. 


Bitblts aren’t displayed. 


Width or size is zero. 




Color is the same as back- 
ground. 
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D 



Sample Programs 



This chapter contains sample SunCGI programs written in C. Refer to Appendix 
E for sample programs that use CGIPW functions and Appendix F for sample 
SunCGI FORTRAN programs . 

D.l. Martini Glass The following program draws a martini glass. The program exits after 10 

seconds. 



#include <cgidefs.h> 

Ccoorlist martinilist ; 

Ccoor glass_coords [10] = { 0,0, 

- 10 , 0 , 

-1.1, 

- 1 , 20 , 

-15,35, 

15,35, 

1 . 20 , 

1 . 1 . 

10 , 0 , 

0,0 }; 

Ccoor water_coords [2 ] = { -12,33, 

12,33 }; 

Ccoor vpll = { -50,-10 }; 

Ccoor vpur = { 50,80 }; 

main { ) 

{ 

Cvwsurf device; 

Cint name; 

NORMAL_VWSURF (device, PIXWINDD) ; 

open_cgi ( ) ; 

open_vws (Sname, Sdevice); 

vdc_extent (&vpll, &vpur) ; 

mart inilist . ptlist = glass_coords ; 

martinilist . n = 10; 

polyline (Smartinilist) ; 

^ - 
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D.2. Tracking Box The following program demonstrates the use of the CGI input functions. A 

square is displayed on the screen and moved with the mouse. The program exits 
if the mouse is still for five seconds. 



#include <cgidefs.h> 

#define DEVNUM 1 /* device number */ 

#define MOUSE_POSITION 5 /* trigger number */ 

#define TIMEOUT (5 * 1000 * 1000) /* timeout in microseconds */ 

Ccoor ulc = {1000, 2000}; 

Ccoor Ire = {2000, 1000}; 

main ( ) 

{ 

Cint name; 

Cvwsurf device; 

Cawresult stat; 

Cinrep sample; /* device measure value */ 

Ccoor samp; /* LOCATOR'S x,y position */ 

Cint trigger; /* trigger number */ 

NORMAL_VWSURF (device, PIXWINDD) ; 
s ample . xypt = & s amp ; 
samp.x = 0; 
samp.y = 27000; 

open_cgi ( ) ; 

open_vws (&name, Sdevice) ; 
set_global_drawing_mode (XOR) ; 

initialize_lid(IC_LOCATOR, DEVNUM, &sample) ; 
associate (MOUSE_POSlTION, IC_LOCATOR, DEVNUM); 
rectangle (&lrc, &ulc) ; /* draw first rectangle */ 

/* wait TIMEOUT micro-seconds for input and check the status */ 
while (request_input (IC_LOCATOR, DEVNUM, TIMEOUT, 

Sstat, Ssample, Strigger) , (stat == VALID_DATA) ) { 

if ( (sample. xypt ->x != ulc.x) | | (sample . xypt ->y != Irc.y) ) { 
rectangle (& Ire, &ulc) ; 

Irc.y = sample . xypt->y; /* move to new location */ 

Irc.x = (sample . xypt ->x + 1000); 

ulc.x = sample .xypt- >x; 

ulc.y = (sample . xypt ->y + 1000); 

< 
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rectangle (&lrc, &ulc) ; 

} 

} 

dissociate (MOUSE_POSITION, IC_LOCATOR, DEVNUM) ; 
release_input_device (IC_LOCATOR, DEVNUM) ; 
close_vws (name) ; 
close_cgi ( ) ; 



D.3. Colored Lines 



The following program draws colored lines. 



r 














tinclude <cgidefs.h> 
#include <stdio.h> 












#def ine 


NCOLORS 64 












#def ine 


MIN 0 












#def ine 


MAX 10000 












typedef 


unsigned char Color; 












static 


Ccoor vpll = { MIN, MIN 


}; 


/* 


lower left corner */ 






static 

main ( ) 
{ 


Ccoor vpur = { MAX, MAX 


}; 


/* 


upper right corner */ 






int name ; 




/* 


view surface name */ 








Cvwsurf device; 




/* 


view surface device * 


/ 






Ccoorlist line; 




/* 


line coordinate list 


*/ 






Ccoor points [2] ; 




/* 


point list */ 








int i ; 




/* 


position counter */ 








Ccentry clist; 




/* 


color map list */ 








Color red[NCOLORS] ; 




/* 


red color map */ 








Color green [NCOLORS] ; 




/* 


green color map */ 








Color blue [NCOLORS] ; 




/* 


blue color map */ 








device. dd = PIXWINDD; 




/* 


select output device 


*/ 






open cgi ( ) ; 




/* 


initilize cgi */ 








open vws (Sname, Sdevice) ; 




/* 


open view surface */ 








vdc_extent (&vpll, Svpur) ; 




/* 


reset vdc space */ 








line width specification mode (ABSOLUTE) ; 












/* 


set the line attributes */ 






line width (1.0); 














for(i=0; KNCOLORS; i++) { 




/* 


set up the color map 


*/ 






red [ i ] = ( i * 3 ) ; 
green [i] = 64; 
blue[i] = 128; 

1 














/ 

clist. n = NCOLORS; 












V 


clist. ra = red; 










j 
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clist.ga = green; 
clist.ba = blue; 

color table (0,&clist); 



for( i=0; KNCOLORS; i++) { 

line.n = 2; 
line.pt list = points; 
line_color (i) ; 
points [0].y = MIN; 
points [0].x = (i*1000) ; 
points [l].y = MAX; 
points [l].x = (i*1000) ; 
polyline (&line) ; 



/* draw a line */ 



sleep (3) ; 

close_vws (name) ; 
close_cgi {) ; 
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Using SunCGI and Pixwins 



This appendix describes how to add the richness of CGI’s primitives (such as cir- 
cles and arcs) to the Pixwins application through CGIPW. To accomplish this, 
you must first write a standard Pixwins program, which brings up windows and 
controls the events delivered to them with the notifier. You may then add the 
CGIPW functions, thus enabling you to draw with both the CGI and Pixwins out- 
put primitives. 

With the CGIPW functions, you can also combine CGI with Pixwins' ability to 
manage multiple (potentially overlapping) windows. The CGI standard does not 
provide facilities for dealing with multiple overlapping windows. 



The command line to compile a CGIPW program is as follows: 




where box . c is the source program. 

Many CGI calls have been replaced with CGIPW calls. For example, 
cgipw_j)olyline ( ) replaces polyline ( ) . The first argument of each 
CGIPW function is a pixwin descriptor of type Ccgiwin. 

The file <cgipw . h> must be included in the CGIPW application program 
instead of <cgidef s . h>. 

E.l. SunCGI — Pixwins The five functions open__pw_cgi ( ) , open_cgi_pw ( ) , 

Interface open_cgi_canvas (), close_cgi_pw{) and close_pw_cgi () are 

necessary for managing the SunCGI - Pixwins interface. 

Open Pixwin CGI Cerror open_pw_cgi ( ) 

open_pw_cgi ( ) initializes CGI by setting the attributes to the default values 
and setting the VDC to device coordinates (i.e. Pixwin coordinates) mapping to 
1:1. Therefore, all input and output primitives will use device coordinates. 

NOTE As in Pixwins coordinates, the origin of the device coordinates is in the upper 
left-hand corner instead of the lower left-hand corner. 

This appendix assumes familiarity with both SunCGI and Pixwins. See the SunView 1 Programmer’ s 
Guide for designing the application’s Pixwins windows, input, color usage, and output. 
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Open a CGI Pixwin 



Open a CGI Canvas 



The entire window is used, not just a square region within it. No standard errors 
are specified for open_pw_cgi ( ) . If open__pw_cgi ( ) returns a nonzero 
result, then the initialization failed. open_j>w_cgi ( ) corresponds to 
open_cgi ( ) . 



Cerror open_cgi_pw (pw, desc, name) 
struct pixwin *pw; /* pixwin */ 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

Cint *name; 



open_cgi_pw ( ) informs CGI of the pixwin pointed to by pw. Calls to CGI 
primitives may then reference this pixwin. However, CGI does not guarantee that 
a pixwin exists or is in any other way properly initialized, desc is a pointer to a 
CGI pixwin descriptor allocated by the application program and defined by 
open_cgi_pw ( ) . It will be used as the first argument to CGIPW functions. 
Calls may also be made to any pixwin function. Multiple calls to 
open_cgi_pw ( ) with pointers to different Ccgiwin stmctures will allow 
primitives to be displayed on multiple view surfaces by repeating calls to CGIPW 
functions with different Ccgiwin descriptors. Attributes are local to the pixwin 
associated with the CGI descriptor passed to the CGIPW attribute functions. 
open_cgi_pw ( ) corresponds to open_vws ( ) . open_pw_cgi { ) must be 
called prior to open_cgi_pw ( ) ; otherwise, error 1 1 1 is returned. Other errors 
(as with open_vws ( ) ) may also be detected. 



ENOTOPOP [5] 

ENOWSTYP til] 
EMAXVSOP [12] 
EMEMSPAC [110] 
ENOTCSTD [111] 



CGI not in proper state: CGI shall be either in state CGOP, 
VSOP, orVSAC. 

Specified view surface type does not exist. 

Maximum number of view surfaces already open. 

Space allocation has failed. 

Ftmction or argument not compatible with standard CGI. 



Cerror open_cgi_canvas (canvas, desc, name) 

Canvas canvas; 

Ccgiwin *desc; 

Cint *name; 

open_cgi_canvas ( ) is a view surface initialization function for compatibil- 
ity with SunView canvases. This must be used instead of open_cgi_pw ( ) , so 
SunCGI knows to handle coordinate transformation and window repainting in a 
way that is compatible with the Canvas package. 

open_cgi_canvas ( ) is used in place of open_cgi_pw ( ) to initialize 
SunCGI to use a canvas. This gives SunCGI the canvas handle, which is a 
higher-level object than a pixwin. After calling this initialization function, the 
resultant descriptor can be treated like that from open_cgi_pw { ) for calling 
any CGIPW function, including close_cgi_pw ( ) . Note that a canvas is a 
pointer to the canvas handle of type Canvas returned by window_create ( ) . 

With the exception of input functions, CGIPW functions should work correctly 
with canvases. In particular, the new SunCGI extension 
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Close a CGI Pixwin 



Close Pixwin CGI 



E.2. Using CGIPW 



cgipw_set_vdc_extent ( ) will correctly map the VDC extent to the under- 
lying canvas. SunCGI input should not be used with canvases, since the Canvas 
package handles all input events on the canvas by calling a client handler func- 
tion. SunCGI has no knowledge of this handler, and would consume input events 
the Canvas package expects, thus interfering with scrollbars and tool border 
functions such as menus. 

Cerror close_cgi_pw (desc) 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

close_cgi_pw ( ) takes the CGI pixwin descriptor desc as an argument and 
removes it from the list of pixwins to which CGI writes. The pixwin is not 
closed. close_cgi_pw ( ) corresponds to close_vws ( ) , and may return 
any of the errors close_vws ( ) detects (except 1 12). 

ENOTOPOP [5] CGI not in proper state: CGI shall be either in state CGOP, 
VSOP, orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 

Cerror close^w_cgi ( ) 

close_pw_cgi ( ) takes care of leaving CGI in an orderly state. This function 
should be caUed before exiting the application program. close_pw_cgi ( ) 
corresponds to close_cgi { ) . 

ENOTOPOP [5] CGI not in proper state: CGI should be in state CGOP, 
VSOP, orVSAC. 

After calling the two initialization functions (open_pw_cgi ( ) and 
open_cgi_pw ( ) ), the application program may call functions from both the 
Pixwins and CGIPW libraries. 

Since CGIPW functions use a 1:1 mapping from VDC to device coordinates, attri- 
butes in VDC units (such as pattern size and character height) will be huge 
unless they are reset. And because the CGIPW origin is the device coordinate ori- 
gin, the upper left-hand comer, attributes with direction or position (for example, 
pattern reference point and character orientation) have their meaning reversed in 
the y dimension. 

Most CGIPW functions do not print error messages even if the error warning 
mask is INTERRUPT or POLL. They all return error codes which may be tested. 

NOTE The application program should not use both SunCGI and window system input 

functions, since both SunCGI and the window system share a common event 
queue. For example, events handled by a SunCGI function will not be handled 
by a window system call after the SunCGI call. However, 
pw_j)utcolormap ( ) calls before, within, and after the call to open CGIPW 
will change the colormap. 
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E.3. CGIPW Functions Table E-1 contains a list of ftinctions available in CGIPW. If a function is not 

included in this table, then use the normal SunCGI function except as described 
in Table E-2. SunCGI fimctions incompatible with CGIPW are given in Table E- 
2 . 

Most of the functions listed in Table E-1 are output and attribute functions; how- 
ever, the tracking functions are listed so that you can control which surfaces 
input devices echo on. The arguments of the CGIPW fimctions are the same as 
those of the SunCGI fimctions except that the first argument is always a desc 
argument of type Ccgiwin. desc is a pointer to a pixwin descriptor filled in by 
the open_cgi_pw { ) function. 

partial_polygon ( ) may be used with cgipw_polygon ( ) , but the glo- 
bal polygon list is freed after use by cgipw_polygon ( ) , so calls to 
partial_polygon ( ) must be repeated prior to use of cgipw_polygon ( ) 
on another view surface. 

Table E- 1 List of CGIPW Functions 



append text (flag, tstring) 


cgipw_append text (desc, flag, tstring) 




cell array (p, q, r, dx, dy, colorind) 


cgipw_cell_ar ray (desc, p, q, r, dx, dy, colorind) 


character expansion_f actor (sfac) 


cgipw_character_expansion_factor (desc, sfac) 


character height (height) 


cgipw_character_height (desc, height) 




character orientation (xbase, ybase. 


cgipw_character_orientation (desc, xbase. 


ybase. 


xup, yup) 


xup, yup) 




character path (path) 


cgipw_character_path (desc, path) 




character set_index (index) 


cgipw_character_set index (desc, index) 




character spacing (spcratio) 


cgipw_character_spacing (desc, spcratio) 




circle (cl, rad) 


cgipw_circle (desc, cl, rad) 




circular_arc_3pt (cl, c2, c3) 


cgipw_circular_arc_3pt (desc, cl, c2, c3) 




circular_arc_3pt close (cl, c2, c3. 


cgipw circular arc 3pt close (desc, cl, c2 


, c3. 


close) 


close) 




circular_arc_center (cl , c2x, c2y. 


cgipw_circular_arc_center (desc, cl, c2x. 


c2y. 


c3x, c3y, rad) 


c3x, c3y, rad) 




circular arc center close (cl, c2x. 


cgipw circular arc center close (desc, cl. 


c2x. 


c2y, c3x, c3y, rad, close) 


c2y, c3x, c3y, rad, close) 




color table (istart, clist) 


cgipw_color table (desc, istart, clist) 




define bundle index (index) 


cgipw_define bundle index (desc, index) 




dis joint_polyline (polycoors) 


cgipw_dis joint__polyline (desc, polycoors) 




ellipse (cl, majx, miny) 


cgipw_ellipse (desc, cl, majx, miny) 




elliptical_arc (cl , sx, sy, ex, ey. 


cgipw_elliptical_arc (desc, cl, sx, sy, ex 


, ey. 


majx, miny) 


majx, miny) 




elliptical_arc_close (cl, sx, sy, ex. 


cgipw_elliptical_arc close (desc, cl, sx. 


sy, ex. 


ey, majx, miny, close) 


ey, majx, miny, close) 




fill area bundle index (index) 


cgipw_fill_area_bundle_index (desc, index) 




fill color (color) 


cgipw_fill_color (desc, color) 




fixed font (index) 


cgipw_fixed font (desc, index) 




hatch index (index) 


cgipw_hatch index (desc, index); 




inquire_aspect_source_f lags () 


cgipw_inquire_aspect source flags (desc) ; 




inquire_f ill_area_attributes () 


cgipw_inquire_fill_area attributes (desc) ; 
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SunCGI Function Name 



CGIPW Function Name 
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T able E- 1 List of CGIPW Functions — Continued 



SunCGI Function Name 


CGIPW Function Name 


inquire_line_attributes () 


cgipw_inquire line attributes (desc) ; 


inquire_marker_attributes () 


cgipw_inquire marker_attributes (desc) ; 


inquire_text_attributes () 


cgipw inquire text attributes (desc) ; 


inquire_text_extent (tstring. 


cgipw_inquire_text extent (desc, tstring. 


nextchar, concat, lleft, uleft, 
uright ) 


nextchar, concat, lleft, uleft, uright) 


interior style (istyle, perimvis) 


cgipw interior style (desc, istyle, perimvis) 


line color (index) 


cgipw line color (desc, index) 


line endstyle (ttyp) 


cgipw_line_endstyle (desc, ttyp) 


line type (ttyp) 


cgipw_line_type (desc, ttyp) 


line width (index) 


cgipw line width (desc, index) 


line width specif ication_mode (mode) 


cgipw line width specification mode (desc, mode) 


marker color (index) 


cgipw marker color (desc, index) 


marker size (index) 


cgipw marker size (desc, index) 


marker size specif ication_mode (mode) 


cgipw_marker_size specif ication_mode (desc, mode) 


marker_type (ttyp) 


cgipw marker type (desc, ttyp) 


pattern index (index) 


cgipw pattern index (desc, index); 


pattern_ref erence_point (open) 


cgipw pattern ref erence_point (desc, open) 


pattern size(dx, dy) 


cgipw_pattern size (desc, dx, dy) 


perimeter_color (index) 


cgipw perimeter color (desc, index) 


perimeter type (ttyp) 


cgipw_perimeter type (desc, ttyp) 


perimeter width (width) 


cgipw_perimeter_width (desc, width) 


perimeter width specification mode (mode) 


cgipw_perimeter_width_specif ication mode (desc, 
mode) 


pixel array (pcell, m, n, colorind) 


cgipw_pixel_array (desc, pcell, m, n, colorind) 


polygon (polycoors) 


cgipw polygon (desc, polycoors) 


polyline (polycoors) 


cgipw polyline (desc, polycoors) 


polyline bundle index (index) 


cgipw_polyline_bundle_index (desc, index) 


polymarker (polycoors) 


cgipw_polymarker (desc, polycoors) 


polymarker bundle_index (index) 


cgipw polymarker bundle index (desc, index) 


rectangle (Ire, ulc) 


cgipw rectangle (desc. Ire, ulc) 


set aspect source flags (flags) 


cgipw set aspect source flags (desc, flags) 


text (cl, tstring) 


cgipw text (desc, cl, tstring) 


text alignment (halign, valign. 


cgipw_text_alignment (desc, halign, valign. 


hcalind, vcalind) 


hcalind, vcalind) 


text_bundle index (index) 


cgipw_text_bundle_index (desc, index) 


text_color (index) 


cgipw_text_color (desc, index) 


text_font_index (index) 


cgipw_text_font_index (desc, index) 


text_precision (ttyp) 


cgipw_text_precision (desc, ttyp) 


vdc extent) cl, c2) 


cgipw_set_vdc extent) desc, cl, c2) 


vdm text (cl, flag, tstring) 


cgipw_vdm_t ext (desc, cl, flag, tstring) 
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Table E-2 SunCGI Functions not Compatible with CGIPW Mode 



Function 


Discussion 


clear_control ( ) t 


All clear extents are identical 


clip_indicator ( ) t 


when cflag is 
CLIP_RECTANGLE 


clip_rectangle ( ) t 


Instead, use pw_region ( ) 
prior to open_cgi_pw ( ) 


close_cgi ( ) t 


Use close pw cgi() 


close_vws ( ) t 


Use close_cgi_pw () 


device_viewport () t 


use pw_r egion ( ) prior to 
open cgi_pw() 


open_cgi ( ) 


Use open_pw_cgi ( ) 


open_vws ( ) t 


Use open cgi__pw ( ) 


partial polygon {) 


global polygon list is freed 
after cgipw polygon () 



t This function produces error ENOTCCPW [112] 

E.4. Example Programs The following example program creates a SunView canvas. When the user clicks 

the left mouse button, CGIPW draws a triangle inside a lO-by-10 rectangle. 
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tinclude <suntool/sunview .h> 
#include <suntool/canvas . h> 
#include <cgipw.h> 



/* 

* SunView window handles 
*/ 

Frame frame; 

Canvas canvas; 

/* 

* CGIPW canvas 
*/ 

Ccgiwin vpw; 



/* 

•k 

*/ 



Canvas event handler 



canvas_event_proc ( window, event) 

Window window; /* unused */ 

Event * event; 

{ 

if (event_is_down ( event)) 
return; 

switch (event_id( event)) { 
case MS_LEFT: 

draw_box_at ( event_x ( event), event_y ( event)); 
break ; 

case MS_MIDDLE: 

print f ( "print_canva s_event : 0); 
print f ( "canvas x,y = (%d,%d)0, 

event_x (event ) , event_y (event ) ) ; 
canvas_window_event ( canvas, event) ; 
printf ( "pixwin region x,y = (%d,%d)0, 

event_x (event) , event_y (event) ) ; 
break; 

case MS_RIGHT: 

window_done ( frame) ; 
close_cgi_pw ( &vpw) ; 
close_jpw_cgi () ; 

exit (0) ; 



} 



default : 

break; 



} 
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main () 

{ 

Cint name; /* goes unused in this example */ 

frame = window_create ( NULL, FRAME, 0); 

canvas = window_create ( frame, CANVAS, 
CANVAS_AUTO_SHRI NK , FALSE , 

WIN_EVENT_PROC, canvas_event_proc, 

CANVAS_WIDTH, 1000, 

CANVAS_HE I GHT , 1000, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create ( 0) , 
WIN_HORIZONTAL_SCROLLBAR, scrollbar_create (0) , 
0 ); 

open_pw_cgi () ; 

open_cgi_canvas ( canvas, &vpw, &name) ; 

window_main_loop ( frame); 

} 



/* 

* draw_box_at () 

* 

* Draw a rectangular box using the passed x,y point as 

* the upper left corner of the box. 

*/ 

draw_box_at (x,y) 
int x,y; 

{ 

Ccoor lr,ul; 

Ccoor triangle [3]; 

Ccoorlist coorlist; 

ul.x = x; 
ul.y = y; 

Ir.x = X + 10; 

Ir.y = y + 10; 

cgipw_rectangle ( &vpw. Sir, &ul) ; 

triangle [0] .X = x+2 ; 

triangle [0] .y = y+7; 

triangle [1] .X = x+8; 

triangle [1] .y = y + 7; 

triangle [2] .x = x + 5; 

triangle [2] .y = y + 2; 

coorlist. n = 3; 

coorlist .ptlist = triangle; 

cgipw_polygon ( &vpw, Scoorlist) ; 

} 



The next example draws using SunView and CGIPW operations in a canvas. If 
SunView color is initialized, the SunView output primitives and the CGIPW out- 
put primitives both recognize the SunView colormap. 
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tinclude 


<suntool/ sunview . h> 


#include 


<suntool/panel .h> 


# include 


<suntool/canvas .h> 


#include 


<suntool/ scrollbar .h> 


finclude 


<sunwindow/ notify .h> 


finclude 


<cgipw . h> 


tinclude 


<math . h> 


Frame 


f rame ; 


Panel 


panel; 


Panel_item 


button; 


int 


button_notify ( ) ; 


Canvas 


canvas; 


Pixwin 


*pw; 


Ccgiwin 


desc ; 


Cint 


name ; 


u char 


red [8], green [8], blue 


main ( ) 





initialize_sunview O ; 
set_up_sunview_colors () ; 
initialize_cgipw ( ) ; 
window main loop { frame); 



initialize_sunview ( ) /* initialize Sunview */ 

{ 

frame = window_create ( NULL, FRAME, 0); 

panel = window_create (frame, PANEL, 0); 
button= panel_create_item ( panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, "Draw", 4,0), 

PANEL_NOTIFY_PROC, button_not if y, 

0 ) ; 

window_f it_height ( panel) ; 



canvas= window_create (frame, CANVAS, 
CANVAS_RETAINED , 
CANVAS_WIDTH, 
CANVAS_HEIGHT, 
WIN_VERTICAL_SCROLLBAR, 
WIN_HORIZONTAL_SCROLLBAR, 
C ANVAS_F I XED_IMAGE , 
CANVAS_AUTO_EXP AND , 
CANVAS_AUTO_SHRINK, 

0 ) ; 



TRUE, 

750, 

750, 

scrollbar_create ( 0 ) , 
scrollbar_create (0) , 
TRUE, 

FALSE, 

FALSE, 



pw = canvas pixwin ( canvas); 
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/* initialize cgi, view surface */ 



int 

initialize_cgipw ( ) 

{ 

open_pw_cgi ( ) / 
open_cgi_canvas { canvas, Sdesc, Sname) ; 

} 

button_notify { ) 

{ 

Ccoor center; 

Cint radius; 

printf ("we are in the panel button notify procO) ; 
pw_vector (pw, 000, 000, 100, 100, PIX_SRC| PIX_COLOR (1) , 1) ; 

pw_vector (pw, 100, 100, 200, 200, PIX_SRC| PIX_COLOR (2 ) , 1) ; 

pw_vector (pw, 200, 200, 300, 300, PIX_SRC| PIX_COLOR (3) , 1) ; 

pw_vector (pw, 300, 300, 400, 400, PIX_SRC| PIX_COLOR (4) , 1) ; 

pw_vector (pw, 400, 400, 500, 500, PIX_SRC| PIX_COLOR (5) , 1) ; 

pw_vector (pw, 500, 500, 600, 600, PIX_SRC| P IX_COLOR ( 6 ) , 1) ; 

pw_text { pw, 20, 20, PIX_SRC 1 PIX_COLOR (7 ) , 0, "canvas text") ; 

interior_style ( SOLIDI, ON) ; 

perimeter_color ( 3); /* set perimeter color */ 

fill_color( 3); /* set fill color */ 

center. X = 400; 
center.y = 400; 
radius = 50; 

cgipw_circle ( &desc, &center, radius); 



set_up_sunview_colors ( ) 

{ 

/* initialize Sunview colormap */ 



red[0] = 255 


green [0] = 255; 


blue[0] = 255; 


/* 


white */ 


red[l] = 000, 


green [1] = 255; 


blue[l] - 000; 


/* 


green */ 


red[2] = 000, 


green [2] = 000; 


blue [2] = 255; 


/* 


blue */ 


red[3] = 255, 


green [3] = 255; 


blue [3] = 0 00; 


/* 


yellow */ 


red[4] = 000, 


green [4] = 255; 


blue [4] = 255; 


/* 


aqua */ 


red[5] = 255, 


green [5] = 000; 


blue [5] = 255; 


/* 


purple */ 


red[6] = 255, 


green [ 6 ] = 000; 


blue [6] = 000; 


/* 


red */ 


red[7] = 000, 


green [7] = 000; 


blue[7] = 000; 


/* 


black */ 



pw_setcmsname ( pw, "my_colors") ; 
pw_putcolormap (pw, 0, 8, red, green, blue); 



Revision A, of 9 May 1988 







Using SunCGI with FORTRAN Pro- 
grams 



Using SunCGI with FORTRAN Programs 155 

F.l. Programming Tips 155 

F.2. Example Programs 156 

F.3. FORTRAN Interfaces to SunCGI 160 






F 

•^X<<wX•!❖^^^^!wX*X•!w^^Is^HKw!<^<<•I•I•X•{vW■IwW•^^t<‘^Xw!w^^{•^•^XwX•?X•X*^^^^^X•^X❖^^ 

Using SunCGI with FORTRAN 

Programs 



All functions provided in SunCGI may be called from FORTRAN programs by 
linking them with the libcgiV 7 . a library. This is done by using the/77 com- 
piler with a command line like: 




where box . f is the FORTRAN source program. Note that libcgi . a must be 
linked with the program (the -Icgi option), and libcgi 7 7 . a must precede it 
(the -Icgi 7 7 option). 



Defined constants may be referenced in source programs by including 
cgidef s7 7 . h. In a FORTRAN program, this must be done via a source state- 
ment like: 




This include statement must be in each FORTRAN program unit which uses the 
defined constants, not just once in each source program file. 

In the Sun release of FORTRAN, names are restricted to sixteen characters in 
length and may not contain the underline character. For this reason, FORTRAN 
programs must use abbreviated names to call the corresponding SunCGI func- 
tions. The correspondence between the full SunCGI names and the FORTRAN 
names appears later in this appendix. In addition, FORTRAN declarations for all 
SunCGI functions appear at the end of this appendix. 

F.l. Programming Tips □ The abbreviated names of the SunCGI functions are less readable than the full 

length names because the underline character cannot be used in the FORTRAN 
names. However, since FORTRAN doesn’t distinguish between upper-case and 
lower-case letters in names, upper-case characters can be used to improve rea- 
dability. 

□ Character strings passed from FORTRAN programs to SunCGI cannot be 
longer than 256 characters. 

□ Pointers returned by C functions are handled in FORTRAN as integer *4 
values, and exist solely to be passed to other Sun graphics functions. 
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□ FORTRAN passes all arguments by reference. Although some SunCGI func- 
tions receive arguments by value, the FORTRAN programmer need not worry 
about this. The interface routines in /usr/lib/libcgi7 7 . a handle tiiis 
situation correctly. When in doubt, look at the FORTRAN declarations for 
SunCGI functions at the end of this appendix. 

□ Some SunCGI functions have stmctures as arguments or return values. These 
are handled in FORTRAN by unbundling the structures into separate argu- 
ments. In general, these will be in the same order, and have the same names, 
as the members of the C structures. One exception is the Ccoorlist struc- 
ture, which is replaced in FORTRAN with an array of x’s, and one of y’s, rather 
than an array of x-y pairs. You may need to consult both the C and FORTRAN 
documentation to determine which FORTRAN arguments are input values, and 
which are output. 

□ Since FORTRAN does not distinguish between upper-case letters and lower- 
case letters in identifiers, any FORTRAN program unit which includes the 
cgidef s7 7 . h header file cannot use the same spelling as any constant 
defined in that header file, regardless of case. 

□ The function cf qoutcap returns the FORTRAN binding names of the output 
capabilities, rather than the C bindings. This is an exception to the rule that 
the FORTRAN library provides a transparent interface to the C functions. 

F.2. Example Programs The following example is the FORTRAN equivalent of the very simple program 

for drawing a martini glass. 



include ”/usr/ include/ £77 /cgidef s77 .h" 
parameter (ibignum=256) 
integer name 

character screenname* (ibigniam) 

integer screenlen 

character windowname* (ib'i gnum) 

integer windowlen 

integer windowfd 

integer retained 

integer dd 

integer cmapsize 

character cmapname* (ibignum) 

integer cmaplen 

integer flags 

character ptr* (ibignum) 

integer noargs 

integer xc(lO), yc(lO), n 
integer xc2 (2) , yc2 (2) 

data xc /O, -10, -1, -1, -15, 15, 1, 1, 10, 
data yc /O, 0, 1, 20, 35, 35, 20, 1, 0, 

data xc2 /-12, 12/ 
data yc2 /33, 33/ 



0 / 

0 / 
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o o 



c 

c 

c 



Initialize CGI and view surface 



C 



call cfopencgiO 
dd = 4 

call cfopenvws (name, screenname, windowname, 
windowfd, retained, dd ,cmapsize, 
cmapname, flags, ptr, noargs) 
call cfvdcext ( -50, -10, 50, 80) 

Set clipping off 



call cfclipind(O) 

C 

C Draw the martini glass 

C 

n = 10 

call cfpolyline ( xc, yc, n) 
n = 2 

call cfpolyline ( xc2, yc2, n) 

C 

C Display the glass for 5 seconds 

C 

call sleep (5) 

C 

C Terminate graphics 

C 

call cfclosevws (name) 
call cfclosecgiO 
call exit () 
end 






program fVVcolors 



include ' /.usr/include/f77/cgidef s77 .h' 

integer name 

integer x(2),y(2) 

integer ncolors 

integer red (8) , grn (8) , blu (8) 

ncolors = 8 
C 

C Open CGI 
C 

call cfopencgi () 

C 

C Open a view surface 
C 

call cfopenvws (name, 0, 0, 0, 1 , CGPIXWINDD, ncolors , ' Color' ,0,0) 
C 

C Set color map 
C 

call setupcolors ( red, grn, blu) 

C 

C Assign the color map 
C 

call cf cotable (1 , red, grn, blu, ncolors) 

C 

C Draw the lines 
C 

do 11 i = 1, ncolors 

call cflncolor(i) 
x(l) = i * 2000 

y(i) = 0 

x(l) = i * 2000 

y(2) = 30000 

call cfpolyline (x, y, 2) 

11 continue 
C 

C Wait 10 seconds 
C 

call sleep (10) 

C 

C Close CGI 
C 

call cfclosevws (name) 
call cfclosecgiO 
end 

C 

C Subroutine to set up the colormap 
C 

subroutine setupcolors ( red, grn, blu) 
integer red ( 8 ) 
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integer grn(8) 
integer blu(8) 

C Set up colormap similar to the default colormap 
C on page 76 except the first color is white, and 
C the last color is black. 

C 



red(l) 


- 


255 


grn(l) 


= 


255 


blu(l) 


= 


255 


red (2) 


= 


255 


grn (2) 


= 


0 


blu (2) 


= 


0 


red (3) 


= 


255 


grn (3) 


= 


255 


blu (3) 


= 


0 


red (4 ) 


= 


0 


grn (4) 


= 


255 


blu (4) 


= 


0 


red (5) 




0 


grn (5) 


= 


128 


blu (5) 


= 


128 


red ( 6 ) 


= 


0 


grn (6) 


= 


0 


blu (6) 


= 


255 


red (7) 


= 


128 


grn (7) 


= 


0 


blu (7) 


= 


128 


red (8) 


= 


0 


grn (8) 


= 


0 


blu (8) 


= 


0 


return 






end 
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F.3. FORTRAN Interfaces 
to SunCGI 



Note: Although all SunCGI procedures are declared here as functions, each may 
also be called as a subroutine if the user does not want to check the returned 
value. 



Table F-1 SunCGI FORTRAN Binding - Part I 



CGI Specification Name 
Activate View Surface 
(SunCGI Extension) 



FORTRAN Binding 

integer function cf act vws (name) 
integer name 



AppendTeXt integer function cfaptext (flag, string) 

integer flag 
character* (*) string 



Associate integer function cfassoc (trigger , devclass, devnum) 

integer trigger 
integer devclass 
integer devnum 



Await Event 



Bitblt Pattern Array 



integer function cfawaitev (timeout, valid, devclass, 

1 devnum, x, y, xlist, ylist, n, val, choice, string, 

2 segid, pickid, message_link, replost, time_stamp, 

3 qstat, overflow) 
integer timeout 
integer valid 
integer devclass 
integer devnum 
integer x, y 
integer xlist (*) 
integer ylist (*) 
integer n 

real val 
integer choice 
character* (*) string 
integer segid 
integer pickid 
integer message_link 
integer replost 
integer time_stamp 
integer qstat 
integer overflow 



integer 
1 rx, 
integer 
integer 
integer 
integer 
integer 
integer 
integer 



function cfbtblpatarr (pixpat , 

ry, ox, oy, dx, dy, name) 

pixpat 

px, py 

pixtarget 

rx, ry 

ox, oy 

dx, dy 

name 



px, py. 



pixtarget. 
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T able F- 1 SunCGI FORTRAN Binding - Part I — Continued 



CGI Specification Name 


FORTRAN Binding 


Bitblt Patterned Source 
Array 


integer function cfbtblpatsouarr (pixpat , px, py, pixsource, 

1 sx, sy, pixtarget, rx, ry, ox, oy, dx, dy, name) 

integer pixpat 

integer px, py 

integer pixsource 

integer sx, sy 

integer pixtarget 

integer rx, ry 

integer ox, oy 

integer dx, dy 

integer name 


Bitblt Source Array 


integer function cfbtblsouarr (bit source, xo, yo, xe, ye, 

1 bittarget, xt, yt, name) 

integer*4 bitsource, bittarget 

integer xo, yo, xe, ye, xt, yt 

integer name 


Cell Array 


integer function cfcellarr (px, qx, rx, py, qy, ry, 

1 dx, dy, colorind) 

integer px, py 

integer qx, qy 

integer rx, ry 

integer dx, dy 

integer colorind (*) 


Character Expansion 
Factor 


integer function cf charexpfac (efac) 
real efac 


Character Height 


integer function cfcharheight (height) 
integer height 


Character Orientation 


integer function cfcharorient (bx, by, dx, dy) 
real bx, by, dx, dy 


Character Path 


integer function cfcharpath (path) 
integer path 


Character Set Index 


integer function cfcharsetix (index) 
integer index 


Character Spacing 


integer function cfcharspacing (efac) 
real efac 


Circle 


integer function cfcircle(x, y, rad) 
integer x 
integer y 
integer rad 


Circular Arc 3pt Close 


integer function cfcircarcthreecl (clx, cly, c2x, c2y, 
1 c3x, c3y, close) 

integer clx, cly, c2x, c2y, c3x, c3y 
integer close 


Circular Arc 3pt 


integer function cf circarcthree (clx, cly, c2x, c2y, 
1 c3x, c3y) 

integer clx, cly, c2x, c2y, c3x, c3y 
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Table F- 1 SunCGI FORTRAN Binding - Part / — Continued 



CGI Specification Name 


FORTRAN Binding 


Circular Arc Center 
Close 


integer function cfcircarccentcl (clx, cly, c2x, c2y, 

1 c3x, c3y, rad, close) 

integer clx, cly, c2x, c2y, c3x, c3y 

integer rad 

integer close 


Circular Arc Center 


integer function cfcircarccent (clx, cly, c2x, c2y, c3x, 
1 c3y, rad) 

integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 


Clear Control 


integer function cfclrcont (soft , hard, intern, extent) 
integer soft, hard 
integer intern 
integer extent 


Clear View Surface 


integer function cfclrvws (name, defflag, color) 
integer name 
integer defflag 
integer color 


Clip Indicator 


integer function cfclipind (f lag) 
integer flag 


Clip Rectangle 


integer function cfcliprect (xmin, xmax, ymin, ymax) 
integer xmin, xmax, ymin, ymax 


Close CGI 
(SunCGI Extension) 


integer function cfclosecgiO 


Close View Surface 
(SunCGI Extension) 


integer function cfclosevws (name) 
integer name 


Table F-2 


SunCGI FORTRAN Binding - Part II 


CGI Specification Name 


FORTRAN Binding 


Color Table 


integer function cf cotable (i start , ra, ga, ba, n) 

integer istart 

integer ra(*), ga (*) , ba(*) 

integer n 


Deactivate View Surface 
(SunCGI Extension) 


integer function cfdeactvws (name) 
integer name 
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Table F-2 SunCGI FORTRAN Binding - Part II — Continued 

FORTRAN Binding 

integer function cfdefbundix (index, linetype, linewidth, 

1 linecolor, marktype, marksize, markcolor, intstyle, 

2 batchindex, pattindex, fillcolor, perimtype, 

3 perimwidth, perimcolor, tSextfont, textprec, 

4 charexpand, charspace, textcolor) 

integer index 
integer linetype 
real linewidth 
integer linecolor 
integer marktype 
real marksize 
integer markcolor 
integer intstyle 
integer batchindex 
integer pattindex 
integer fillcolor 
integer perimtype 
real perimwidth 
integer perimcolor 
integer tSextfont 
integer textprec 
real charexpand 
real charspace 
integer textcolor 

Device Viewport integer function cfdevvpt (name, xbot, ybot, xtop, ytop) 

integer name 

integer xbot, ybot, xtop, ytop 

Disable Events integer function cfdaevents (devclass, devnum) 

integer devclass 
integer devnum 

integer function cfdpolyline (xcoors, ycoors, n) 
integer xcoors (*) 
integer ycoors (*) 
integer n 

Dissociate integer function cfdissoc (trigger, devclass, devnum) 

integer trigger 
integer devclass 
integer devnum 

Ellipse integer function cfellipse(x, y, majx, miny) 

integer x, y 
integer majx, miny 

Elliptical Arc Close integer function cfelliparccl (x, y, sx, sy, ex, ey, 

1 majx, miny, close) 
integer x, y 
integer sx, sy 
integer ex, ey 
integer majx, miny 
integer close 



Disjoint Polyline 



CGI Specification Name 
Define Bundle Index 
(SunCGI Extension) 
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Table F-2 SunCGI FORTRAN Binding - Part II — Continued 



Elliptical Arc integer function cfelliparc (x, y, sx, sy, ex, ey, majx, 

1 miny) 
integer x, y 
integer sx, sy 
integer ex, ey 
integer majx, miny 

Enable Events integer function cfenevents (devclass, devnum) 

integer devclass 
integer devnum 

Fill Area Bundle Index integer function cf f lareabundix (index) 

integer index 

Fill Color integer function cff Icolor (color) 

integer color 

Fixed Font integer function cffixedfont (index) 

(SunCGI Extension) integer index 

Flush Event Queue integer function cfflusheventqu () 

integer function cf get lastreqinp (devclass, devnum, valid, 

1 X, y, xlist, ylist, n, val, choice, string, segid, 

2 pickid) 
integer devclass 
integer devnum 
integer valid 
integer x, y 
integer xlist (*) 
integer ylist (*) 
integer n 
real val 
integer choice 
character* (*) string 
integer segid 
integer pickid 

Hard Reset integer function cfhardrst () 

Hatch Index integer function cfhatchix (index) 

integer index 

Initialize LID integer function cfinitlid (devclass , devnum, x, y, xlist, 

1 ylist, n, val, choice, string, segid, pickid) 

integer devclass 

integer devnum 

integer x, y 

integer xlist (*) 

integer ylist (*) 

integer n 

real val 

integer choice 

character* (*) string 

integer segid 

integer pickid 
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Get Last Requested 
Irq>ut 



CGI Specification Name 



FORTRAN Binding 
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Table F-2 SunCGI FORTRAN Binding - Part II — Continued 



CGI Specification Name 


FORTRAN Binding 


Initiate Request 


integer function cfinitreq(devclass , devnum) 
integer devclass 
integer devnum 


Inquire Aspect Source 
Flags 


integer function cfqasfs (n, num, vals) 
integer n 
integer num(*) 
integer vals(*) 


Inquire Bitblt 
Alignments 


integer function cfqbtblt align (base, width, px, py, 

1 maxpx, maxpy, name) 

integer base 

integer width 

integer px 

integer py 

integer maxpx 

integer maxpy 

integer name 


Inquire Cell Array 


integer function cfqcellarr (name, px, qx, rx, py, qy, 

1 ry, dx, dy, colorind) 

integer name 

integer px, py 

integer qx, qy 

integer rx, ry 

integer dx, dy 

integer colorind (*) 


Inquire Device Bitmap 


integer function cfqdevbtmp (name, map) 
integer name 
integer*4 map 


Inquire Device Class 


integer function cfqdevclass (output , input) 
integer output, input 


Table F-3 


SunCGI FORTRAN Binding - Part III 


CGI Specification Name 


FORTRAN Binding 


Inquire Device 
Identification 


integer function cfqdevid (name, devid) 
integer name 
character* (*) devid 


Inquire Drawing Mode 


integer function cfqdrawmode (visibility, source, 

1 destination, combination) 

integer visibility 

integer source 

integer destination 

integer combination 


Inquire Event Queue 
State 


integer function cfqevque (qstate, qoflow) 
integer qstate 
integer qoflow 
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T able F-3 SunCGI FORTRAN Binding - Part III — Continued 



CGI Specification Name 



Inquire Fill Area 
Attributes 



Inquire Input 
Capabilities 



Inquire LID State List 



FORTRAN Binding 



integer function cfqflareaatts (style, vis, color, hindex, 

1 pindex, bindex, pstyle, pwidth, pcolor) 

integer style, vis, color 

integer hindex, pindex, bindex 

integer pstyle 

real pwidth 

integer pcolor 

integer function cfqinpcaps (valid, numloc, numval, numstrk, 

1 numchoice, numstr, numtrig, evqueue, asynch, coordmap, 

2 echo, tracking, prompt, acknowledgement, trigman) 
integer valid 

integer numloc 
integer numval 
integer numstrk 
integer numchoice 
integer numstr 
integer numtrig 
integer evqueue 
integer asynch 
integer coordmap 
integer echo 
integer tracking 
integer prompt 
integer acknowledgement 
integer trigman 

integer function cfqlidstatelis (devclass , devnum, valid, 

1 state, pronpt, acknowledgement, x, y, xlist, ylist, n, 

2 val, choice, string, segid, pickid, n, triggers, 

3 echotype, echosta, echodat) 
integer devclass 

integer devnum 
integer valid 
integer state 
integer prompt 
integer acknowledgement 
integer x 
integer y 
integer xlist (*) 
integer ylist (*) 
integer n 
real val 
integer choice 
character* (* ) string 
integer segid 
integer pickid 
integer n 

integer triggers (*) 
integer echotype 
integer echosta 
integer echodat 
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Table F-3 SunCGI FORTRAN Binding - Part III — Continued 



Inquire LID State integer function cfqlidstate (devclass, devnum, valid, 

1 state) 
integer devclass 
integer devnum 
integer valid 
integer state 

Inquire LID Capabilities integer function cfqlidcaps (devclass, devnum, valid, 

1 sample, change, numassoc, trigas soc, prompt, 

2 acknowledgement, echo, echotype, n, classdep, state) 
integer devclass 

integer devnum 
integer valid 
integer sample 
integer change 
integer numassoc 
integer trigassoc(*) 
integer prompt 
integer acknowledgement 
integer echo(*) 
integer echotype (*) 
integer n 

character* (* ) classdep 
integer state {*) 

Inquire Line Attributes integer function cfqlnatts (style, width, color, index) 

integer style 
real width 

integer color, index 

integer function cfqmkatts (type, size, color, index) 
integer type 
real size 

integer color, index 

Inquire Output integer function cfqoutcap (first , last, list) 

Capabilities integer first, last 

character*80 list(*) 

Inquire Output Function integer function cfqout f unset (level , support) 

integer level 
integer support 

Inquire Pattern integer function cfqpatatts (cindex, row, column, colorlis. 

Attributes 1 x, y, dx, dy) 

integer cindex 
integer row 
integer column 
integer colorlis (*) 
integer x 
integer y 
integer dx 
integer dy 
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Attributes 



CGI Specification Name 



FORTRAN Binding 
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Table F-3 SunCGI FORTRAN Binding - Part III — Continued 

Inquire Physical integer function cfqphyscsys (name, xbase, ybase, xext, yext, 

Coordinate System i xunits, yunits) 

integer name 
integer xbase, ybase 
integer xext, yext 
real xunits, yunits 

Inquire Pixel Array integer function cfqpixarr (px, py, m, n, colorind, name) 

integer px, py 
integer m, n 
integer colorind (*) 
integer name 

Inquire Text Attributes integer function cfqtextatts (font set, index, cfont, prec, 

1 efac, space, color, hgt, bx, by, ux, uy, path, halign, 

2 valign, hfac, cfac) 

integer font set, index, cfont, prec 

real efac, space 

integer color, hgt 

real bx, by, ux, uy 

integer path, halign, valign 

real hfac, cfac 

Inquire Text Extent integer function cfqtextext (string, nextchar, 

1 conx, cony, llpx, llpy, ulpx, ulpy, urpx, urpy) 
character* (*) string 
character* (*) nextchar 
integer conx 
integer cony 
integer llpx 
integer llpy 
integer ulpx 
integer ulpy 
integer urpx 
integer urpy 

integer function cfqtrigcaps (trigger, valid, change, n, 

1 class, assoc, maxassoc, prompt, acknowledgement, 

2 name, description) 
integer trigger 
integer valid 
integer change 
integer n 
integer class (*) 
integer assoc (*) 
integer maxassoc 
integer prompt 
integer acknowledgement 
character* (*) name 
character* (*) description 



Inquire Trigger 
Capabilities 



CGI Specification Name 



FORTRAN Binding 
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Table F-3 SunCGI FORTRAN Binding - Part HI — Continued 



CGI Specification Name 




FORTRAN Binding 


Inquire Trigger State 


integer function 
1 class, assoc] 

integer trigger 
integer valid 
integer state 
integer n 
integer class (*) 
integer assoc (*) 


cfqtrigstate (trigger, valid, state, n. 


Inquire VDC Type 


integer function 
integer type 


cfqvdctype (type) 


Interior Style 


integer function 
integer istyle 
integer perimvis 


cfintstyle (istyle, perimvis) 


Line Color 


integer function 
integer index 


cf Incolor (index) 


Line Endstyle 


integer function 


cf Inendstyle (ttyp) 


(SunCGI Extension) 


integer ttyp 




Line Type 


integer function 
integer ttyp 


cf Intype (ttyp) 


Line Width Specification 


integer function 


cf Inspecmode (mode) 


Mode 


integer mode 




Table F-4 


SunCGI FORTRAN Binding - Part IV 


CGI Specification Name 




FORTRAN Binding 


Line Width 


integer function 
real index 


cf Inwidth (index) 


Marker Color 


integer function 
integer index 


cfmkcolor (index) 


Marker Size 


integer function 


cfmkspecmode (mode) 


Specification Mode 


integer mode 




Marker Size 


integer function 
real index 


cfmksize (index) 


Marker Type 


integer function 
integer ttyp 


cfmktype (ttyp) 


Open CGI 
(SunCGI Extension) 


integer function 


cfopencgi () 
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Table F-4 SunCGI FORTRAN Binding - Part IV — Continued 



CGI Specification Name 


FORTRAN Binding 


Open View Surface 
( SunCGI Extension ) 


integer function cfopenvws (name, screenname, windowname, 

1 windowfd, retained, dd, cmapsize, cmapname, flags, 

2 ptr) 
integer name 

character* (*) screenname 
character* (*) windowname 
integer windowfd 
integer retained 
integer dd 
integer cmapsize 
character* (*) cmapname 
integer flags 
character* {*) ptr 


Partial Polygon 


integer function cfppolygon (xcoors, ycoors, n, flag) 

integer xcoors (*) 

integer ycoors (*) 

integer n 

integer flag 


Pattern Index 


integer function c f pat ix (index) 
integer index 


Pattern Reference Point 


integer function cfpatrefpt (x, y) 
integer x, y 


Pattern Size 


integer function cfpatsize (dx, dy) 
integer dx, dy 


Pattern Table 


integer function cfpatt able (index, m, n, colorind) 
integer index 
integer m, n 
integer colorind {*) 


Pattern with Fill Color 
( SunCGI Extension ) 


integer function cfpatf illcolor (f lag) 
integer flag 


Perimeter Color 


integer function cfperimcolor (index) 
integer index 


Perimeter Type 


integer function cfperimtype (ttyp) 
integer ttyp 


Perimeter Width 
Specification Mode 


integer function cfperimspecmode (mode) 
integer mode 


Perimeter Width 


integer function cfperimwidth (index) 
real index 


Pixel Array 


integer function cfpixarr(px, py, m, n, colorind) 
integer px, py 
integer m, n 
integer colorind (*) 
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Table F-4 SunCGI FORTRAN Binding - Part TV — Continued 



CGI Specification Name 


FORTRAN Binding 


Polygon 


integer function cfpolygon (xcoors , ycoors, n) 
integer xcoors (*) 
integer ycoors(*) 
integer n 


Polyline Bundle Index 


integer function cf poly Inbundix (index) 
integer index 


Polyline 


integer function cf polyline (xcoors, ycoors, n) 
integer xcoors (*) 
integer ycoors (*) 
integer n 


Polymarker Bundle 
Index 


integer function cfpolymkbundix (index) 
integer index 


Polymarker 


integer function cf polymarker (xcoors, ycoors, n) 
integer xcoors (*) 
integer ycoors (*) 
integer n 


Rectangle 


integer function cf rectangle (xbot , ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 


Release Input Device 


integer function cfrelidev (devclass , devnum) 
integer devclass 
integer devnum 


Table F-5 


SunCGI FORTRAN Binding - Part V 


CGI Specification Name 


FORTRAN Binding 


Request Input 


integer function cfreqinp (devclass, devnum, timeout, 

1 valid, trigger, x, y, xlist, ylist, n, val, choice, string, 

2 segid, trigger, pickid) 
integer devclass 
integer devnum 

integer timeout 
integer valid 
integer trigger 
integer x, y 
integer xlist (*) 
integer ylist (*) 
integer n 
real val 
integer choice 
character* (*) string 
integer segid 
integer pickid 


Reset to Defaults 


integer function cfrsttodef s () 
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Table F-5 SunCGI FORTRAN Binding - Part V — Continued 



CGI Specification Name 



Sample Input 



Selective Flush of Event 
Queue 

Set Aspect Source Flags 

Set Default Trigger 
Associations 

Set Drawing Mode 



Set Error Warning Mask 

Set Global Drawing 
Mode 

(SunCGI Extension) 

Set Initial Value 



FORTRAN Binding 



integer function cf sampinp (devclass , devnum, valid, x, y, 

1 xlist, ylist, n, val, choice, string, segid, pickid) 

integer devclass 

integer devnum 

integer valid 

integer x, y 

integer xlist (*) 

integer ylist (*) 

integer n 

real val 

integer choice 

character* (* ) string 

integer segid 

integer pickid 

integer function cfsflusheventcpj (devclass, devnum) 
integer devclass 
integer devnum 

integer function cf saspsouf lags (fval, fnum, n) 
integer fval(*), fnum(*), n 

integer function cfsdefatrigassoc (devclass , devnum) 
integer devclass 
integer devnum 

integer function cfsdrawmode (visibility, source, 

1 destination, combination) 
integer visibility 
integer source 
integer destination 
integer combination 

integer function cfserrwarnmk (action) 
integer action 

integer function cf sgldrawmode (combination) 
integer combination 



integer function cfsinitval (devclass, devnum, x, y, 

1 xlist, ylist, n, val, choice, string, segid, pickid) 

integer devclass 

integer devnum 

integer x, y 

integer xlist (*) 

integer ylist (*) 

integer n 

real val 

integer choice 

character* (*) string 

integer segid 

integer pickid 
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Table F-5 


SunCGI FORTRAN Binding - Part V — Continued 


CGI Specification Name 


FORTRAN Binding 


Set Up SIGWINCH 
(SunCGI Extension ) 


integer function cf supsig (name, sig function) 
integer name 
external sig_f unction 


Set VALUATOR Range 


integer function cf aval range (devnum, mn, mx) 
integer devnum 
real mn, mx 


Text Alignment 


integer function cftextalign (halign, valign, hcalind, 

1 vcalind) 

integer halign 

integer valign 

real hcalind, vcalind 


Text Bundle Index 


integer function cftextbundix (index) 
integer index 


Text Color 


integer function cftextcolor (index) 
integer index 


Text Font Index 


integer function cftextfontix (index) 
integer index 


Text Precision 


integer function cftextprec (ttyp) 
integer ttyp 


Text 


integer function cftext (x, y, string) 
integer x 
integer y 

character* (*) string 


Track Off 


integer function cftrackoff (devclass, devnum, tracktype, 

1 action) 

integer devclass 

integer devnum 

integer tracktype 

integer action 


Track On 


integer function cftrackon (devclass , devnum, echotype, 

1 exlow, eylow, exup, eyup, x, y, xlist, ylist, n, val, 

2 choice, string, segid, pickid) 
integer devclass 

integer devnum 
integer echotype 
integer exlow 
integer eylow 
integer exup 
integer eyup 
integer x, y 
integer xlist (*) 
integer ylist (*) 
integer n 
real val 
integer choice 
character* (*) string 
integer segid 
integer pickid 
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Table F-5 


SunCGI FORTRAN Binding - Part V — Continued 


CGI Specification Name 


FORTRAN Binding 


VDC Extent 


integer function cf vdcext (xbot , ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 


V DM Text 


integer function cfvdmtext (x, y, flag, string) 

integer x 

integer y 

integer flag 

character* (*) string 
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Short C Binding 



At the time SunCGI was implemented, there was no official ANSI C binding for 
CGI. Sun Microsystems has tried to anticipate the eventual C binding with a set 
of shorter function names. The SunCGI binding is inspired by the C language 
binding of GKS. These names are contained in the header file <cgicbind . h> 
which must be included in an application program using the short C binding. 



Correspondence Between Long and Short C Names 



Long Name 


Short Name 


activate vws() 


Cactvws !) 


append text () 


Captext !) 


associate () 


Cassoc !) 


await_event () 


Cawaitev !) 


bitblt_pattern array () 


Cbtblpatarr !) 


bitblt_patterned source array () 


Cbtblpatsouarr ! ) 


bitblt_source_array () 


Cbtblsouarr !) 


cell_array ( ) 


Ccellarr !) 


character expansion_f actor () 


Ccharexpfac !) 


character height () 


Ccharheight !) 


character orientation!) 


Ccharorientation !) 


character_path () 


Ccharpath ! ) 


character set index () 


Ccharsetix !) 


character spacing!) 


Ccharspacing ! ) 


circle ! ) 


Ccircle ! ) 


circular arc_3pt !) 


Ccircarcthree !) 


circular arc_3pt close!) 


Ccircarcthreecl !) 


circular arc_center!) 


Ccircarccent !) 


circular_arc_center_close () 


Ccircarccentcl !) 


clear control !) 


Cclrcont ! ) 


clear view surface!) 


Cclrvws !) 


clip indicator!) 


Cclipind ! ) 


clip rectangle!) 


Ccliprect !) 


close cgi !) 


Cclosecgi ! ) 


close vws !) 


Cclosevws ! ) 


color table !) 


Ccotable ( ) 


deactivate vws!) 


Cdeactvws ! ) 


define bundle index!) 


Cdefbundix !) 



microsystems 
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Table G- 1 Correspondence Between Long and Short C Names— r Continued 



Lxtng Name 


Short Name 


device_viewport () 


Cdewpt !) 


disable events () 


Cda events !) 


disjoint polyline () 


Cdpolyline ! ) 


dissociate () 


Cdissoc 0 


echo_off {) 


Cechoof f 0 


echo_on () 


Cechoon () 


echo update ( ) 


Cechoupd ! ) 


ellipse 0 


Cellipse ! ) 


elliptical_arc () 


Celliparc !) 


elliptical arc close () 


Celliparccl !) 


enable events () 


Cen events !) 


fill area_bundle_index () 


Cf lareabundix !) 


fill color 0 


Cflcolor !) 


fixed_font () 


Cfixedfont !) 


flush event_queue 0 


Cf lusheventqu !) 


get last requested_input () 


Cgetlastreqinp !) 


hard_reset () 


Chardrst ! ) 


hatch_index {) 


Chatchix ! ) 


initialize_lid ( ) 


Cinitlid!) 


initiate_request {) 


Cinitreq!) 


incjuire aspect source flags () 


Cqasf s ! ) 


inquire bitblt alignments!) 


Cqbtblalign !) 


inquire cell array!) 


Cqcellarr !) 


incjuire device bitmap!) 


Cqdevbtnp ! ) 


inquire device class () 


Cqdevclass ! ) 


inquire device identification () 


Cqdevid !) 


inquire_drawing mode () 


Cqdrawmode ! ) 


inquire event queue state ! ) 


Cqevquestate !) 


inquire_f ill_area_attributes !) 


Cqflareaatts !) 


inquire input capabilities !) 


Cqinpcaps !) 


inquire lid_capabilities () 


Cqlidcaps !) 


inquire_lid_state () 


Cqlidstate ! ) 


inquire_lid_state_list !) 


Cqlidstatelis !) 


inquire line attributes!) 


Cqlnatts () 


inquire_marker_attributes !) 


Cqmkatts () 


inquire_output_capabilities !) 


Cqoutcap!) 


inquire_output_function_set !) 


Cqoutf unset !) 


inquire_^attern attributes !) 


Cqpatatts !) 


inquire_physical_coordinate_system !) 


Cqphyscsys !) 


inquire_pixel array!) 


Cqpixarr ! ) 


inquire text attributes!) 


Cqtextatts ! ) 


inquire_text extent!) 


Cqt extext !) 


inqpiire_trigger_capabilities !) 


Cqtrigcaps !) 


inquire trigger state!) 


Cqtrigstate !) 


inquire vdc_type !) 


Cqvdctype ! ) 


interior style!) 


Cint style !) 
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Table G- 1 Correspondence Between Long and Short C Names — Continued 



Long Name 


Short Name 


line color 0 


Clncolor () 


line endstyle () 


Clnendstyle () 


line type ( ) 


Clntype ( ) 


line_width ( ) 


Clnwidth (} 


line_width_specification_mode () 


Clnwidthspecmode () 


marker_color ( ) 


Cmk color ( ) 


marker size () 


Cmksize () 


marker size_specif ication mode() 


Cmksizespecmode () 


marker type() 


Cmktype ( ) 


open cgi ( ) 


Copen cgi () 


open vws ( ) 


Copen vws ( ) 


partial_polygon {) 


Cppolygon () 


pattern index () 


Cpatix ( ) 


pattern ref erence_j>oint ( ) 


Cpatrefpt () 


pattern size() 


Cpatsize ( ) 


pattern table () 


Cpattable () 


pattern with fill color () 


Cpatf illcolor () 


perimeter_color ( ) 


Cperimcolor () 


perimeter type ( ) 


Cperimtype ( ) 


perimeter width () 


Cperimwidth () 


perimeter_width_specif ication_mode () 


Cperimwidthspecmode () 


pixel array 0 


Cpixarr () 


polygon () 


Cpolygon ( ) 


polyline ( ) 


Cpolyline () 


polyline bundle index () 


Cpolylnbundix () 


polymarker ( ) 


Cpolymarker () 


polymarker bundle Index () 


Cpolymkbundix () 


rectangle ( ) 


Crectangle ( ) 


release input device () 


Crelidev ( ) 


request_input () 


Creqinp ( ) 


reset to defaults () 


Crsttodef s () 


sample_input () 


Csampinp ( ) 


selective_f lush of event queue () 


Cselectf lusheventqu () 


set_aspect_source_f lags () 


Csaspsouf lags () 


set default_trigger associations () 


Csdef atrigassoc ( ) 


set_drawing_mode () 


Csdrawmode ( ) 


set_error_warning_mask () 


Cserrwarnmk () 


set global drawing mode ( ) 


Csgldrawmode ( ) 


set initial value () 


Csinitval () 


set up sigwinchO 


Csupsig 0 


set valuator range () 


Csvalrange ( ) 


text ( ) 


Ctext 0 


text_alignment ( ) 


Ct ext align ( ) 


text bundle index () 


Ctextbundix () 


text_color ( ) 


Ctext color ( ) 


text font_index() 


Ctext font ix () 
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T able G- 1 Correspondence Between Long and Short C Names — Continued 



lA)ng Name 


Short Name 


text precision 0 


Ctextprec () 


track off () 


Ctrackoff () 


track on() 


Ctrackon ( ) 


vdc extent () 


Cvdcext ( ) 


vdin_text () 


Cvdmtext ( ) 
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Index 



A 

Activate View Surface (SunCGI Extension) 

C function, 17 
FORTRAN function, 160 
activate_vws (), 17 
Append Text 

C function, 45 
FORTRAN function, 160 
append_text ( ) , 45 
aspect soxirce flag, see bundles 
associate () , 88 
Associate 

C function, 88 
FORTRAN function, 160 
associations, 28 
adding, 88 
removing, 89 

asynchronous input functions, 94 
attribute inquiries 

inq[uire_aspect_source_flags () , 80 
inquire_f ill_area_attributes () , 78 
inquire_line_attributes (), 78 
inquire_marker_attributes () , 78 
inquire_pattern_attributes () , 79 
inquire_text_attributes ( ) , 79 
attributes, 55 thru 80 
bundled, 57 thru 60 
color, 76 thru 77 
fill area, 64 thru 65 
inquiry, 77 thru 80 
line, 60 thru 62 
pattern, 65 thru 68 
perimeter, 69, 70 
polymarker, 62 thru 64 
solid object, 64 thru 70 
text, 70 thru 76 
Await Event 

C function, 96 
FORTRAN function, 160 
await_event ( ) , 96 

B 

bitblt, 35, 44, 51 
Bitblt Pattern Array 
C function, 47 
FORTRAN function, 160 
Bitblt Patterned Source Array 



Bitblt Patterned Source Array, continued 
C function, 48 
FORTRAN function, 161 
Bitblt Source Array 
C function, 47 
FORTRAN function, 161 
bitblt j>attern_a r ray ( ) , 47 
bitblt_patterned_source_array () , 48 
bitblt_source_array ( ) , 47 
bxmdle 

aspect source flag, 55 
attributes, 57 thru 60 
def ine_bundle_index () , 59 
f ill_area_bundle_index ( ) , 64 
index, 55 

polyline_bundle_index () , 60 
polymarker_bundle_index (), 62 
set_aspect_source_f lags (), 58 
table, 55, 57 

text_bundle_index () , 70 

c 

C function 

activate_vws ( ) , 17 
append_text ( ) , 45 
associate () , 88 
await_event () , 96 
bitblt_pattern_array ( ) , 47 
bitblt^atterned_source_array ( ) , 48 
bitblt_source_array () , 47 
cell_array ( ) , 46 

character_expansion_f actor () , 72 
character_height ( ) , 72 
character_orientation () ,73 
character_j5ath () , 74 
character_set_index () , 71 
character_spacing ( ) , 72 
circle ( ) , 40 
circular_arc_3pt () , 42 
circular_arc_3pt_close (),42 
circular_arc_center 0 ,40 
circular_arc_center_close () , 41 
clear_control ( ) , 22 
clear_view_surface (), 21 
clip_indicator (), 20 
clip_rectangle ( ) , 21 
close_cgi () , 18 
close vws 0 , 17 
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C function, continued 

color_table ( ) , 76 
deactivate_vws (), 17 
define_bundle_index (> , 59 
device_viewport () , 20 
disable_event s () , 99 
disjolnt polyline () ,37 
dissociate () , 89 
ellipse 0 ,43 
elliptical_arc (), 43 
elliptical_arc_close () , 43 
enable_events {) , 96 
fill_area_bundle_index () , 64 
f ill_color ( ) , 65 
f ixed_f ont ( ) , 73 
f lush_event_queue () , 97 
get_last_requested_input (), 98 
hard_reset ( ) , 21 
hatch_index ( ) , 67 
initialize_lid(), 86 
initiate_request ( ) , 94 
inquire_marker_attributes {) , 78 
inquire_aspect_source_f lags () , 80 
inquire_bitblt_alignments () , 50 
inquire_cell_array ( ) , 49 
inquire_device_bitmap 0 , 50 
inquire_device_class () , 26 
inquire_device_identif ication () , 26 
inquire_drawing_mode () , 52 
inquire_event_queue_state () , 100 
incpaire_f ill_area_attributes { ) , 78 
inquire_input_capabilities ( ) , 28 
inquire_lid_capabilities () , 29 
inquire_lid_state () , 100 
inquire_lid_state_list () , 99 
inquire_line_attributes ( ) , 78 
inquire_output_capabilities () , 28 
inquire_output_function_set () , 27 
inquire_pattern_attributes 0 , 79 
inquire_physical_coordinate_system (} , 26 
inquire_jpixel_array () , 49 
inquire_text_attributes ( ) , 79 
inquire_text_extent () , 45 
inquire_trigger_capabilities () , 30 
inquire_trigger_state () , 100 
inquire_vdc_type ( ) , 27 
interior_style ( ) , 64 
line_color ( ) , 62 
line_endstyle () , 61 
line_type () , 60 
line_width ( ) , 62 

line_width_specif ication_mode () , 61 
marker_color ( ) , 64 
marker_size (), 63 

marker_size_specification_mode () , 63 

marker_type ( ) , 63 

open_cgi ( ) , 12 

open_vws ( ) , 13 

partial_polygon () , 38 

pattern_index () , 67 

pattern_reference_point ( ) , 68 

pattern_size () , 68 

pattern_table () , 67 

pattern_with_f ill_color ( ) , 68 



C function, continued 

perimeter_color ( ) , 70 
perimeter_type ( ) , 69 
perimeter_width ( ) , 69 

perimeter_width_specification_mode () , 70 
pixel_array ( ) , 46 
polygon () , 37 
polyline 0,36 

polyline_bundle_index () , 60 
polymarker ( ) , 37 
polymarker_bundle_index () , 62 
rectangle () , 40 
release_input_device ( ) , 87 
rec[uest_input () , 93 
reset_to_default s ( ) , 21 
sample_input (), 98 

selective_f lush_of_event_queue ( ) , 97 
set_aspect_source_f lags {) , 58 
set_default_trigger_associations () , 88 
set_drawing_mode () , 51 
set_error_warning_mask () , 22 
set_global_drawing_mode () , 51 
set_init ial_value ( ) , 89 
set_up_sigwinch ( ) , 24 
set_valuator_range () , 90 
text ( ) , 44 

text_alignment ( ) , 74 
text_bundle_index ( ) , 70 
text_color ( ) , 73 
text_f ont_index 0,71 
text_precision (), 71 
track_off () , 91 
track_on () , 90 
vdc_extent 0,18 
vdm_text () , 44 
Cell Array 

C function, 46 
FORTRAN function, 161 
cell_array () , 46 
cf actvw s ( ) , 160 
cf apt ext ( ) , 160 
cfassoc 0 , 160 
cfawaitev () , 160 
cfbtblpatarr ( ) , 160 
cfbtblpatsouarr () , 161 
cfbtblsouarr ( ) , 161 
cf cellarr () , 161 
cf charexpf ac ( ) , 161 
cf charheight ( ) , 161 
cf charorient ( ) , 161 
cfcharpathO, 161 
cfcharsetix () , 161 
cf charspacing () , 161 
cf circarccent (), 162 
cf circarccentcl ( ) , 162 
cf circarcthree ( ) , 161 
cfcircarcthreecl () , 161 
cf circle ( ) , 161 
cfclipind () , 162 
cfcliprect (), 162 
cfclosecgi (), 162 
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cf closevws 0 , 162 
cfclrcont (), 162 
cf clrvws 0 , 162 
cf cotable ( ) , 162 
cfdaevents () , 163 
cfdeactvws (), 162 
cfdefbundix () , 163 
cfdewpt 0 , 163 
cfdissoc 0 , 163 
cf dpolyline () , 163 
cf elliparc () , 164 
cfelliparccl () , 163 
cf ellipse (), 163 
cfenevents () , 164 
cffixedfont {), 164 
cf f lareabundix 0 , 164 
cfflcolor 0, 164 
cf flusheventc[U () , 164 
cf getlastreqinp () , 164 
cfhardrst (), 164 
cf hatchix ( ) , 164 
cfinitlidO, 164 
cfinitreqO, 165 
cf intstyle () , 169 
cflncolor 0, 169 
cf Inendstyle () , 169 
cf Inspecmode () , 169 
cf Intype () , 169 
cf Inwidth (), 169 
cf mkcolor ( ) , 169 
cfmksize () , 169 
cfmkspecmode () , 169 
cfmktype () , 169 
cfopencgi (), 169 
cf openvws () , 170 
cfpatf illcolor () , 170 
cfpatix () , 170 
cfpatrefpt (), 170 
cf patsize ( ) , 170 
cfpattable (), 170 
cfperimcolor () , 170 
cfperimspecmode () , 170 
cfperimtype (), 170 
cfperimwidth () , 170 
cfpixarr () , 170 
cf polygon () , 171 
cfpolyline 0 , 171 
cfpolylnbundix {) , 171 
cf polymarker () , 171 
cfpolymkbundix () , 171 
cfppolygon (), 170 
cf qasf s ( ) , 165 
cfqbtblt align (), 165 
cfqcellarr 0 , 165 
cf qdevbtmp ( ) , 165 
cfqdevclass (), 165 
cf qdevid ( ) , 165 
cfqdrawmode (), 165 



cfqevque 0, 165 
cfqf lareaatts {), 166 
cfqinpcaps (), 166 
cfqlidcaps (), 167 
cfqlidstate () , 167 
cfqlidstatelis () , 166 
cfqlnatts () , 167 
cfqmkatts (), 167 
cfqoutcap () , 167 
cfqoutf unset ( ) , 167 
cfqpatatts (), 167 
cfcjphyscsys () , 168 
cf cjpixarr ( ) , 168 
cfqtextatts {) , 168 
cfqtextext (), 168 
cfqtrigcaps () , 168 
cf qtrigstate ( ) , 169 
cfqvdctype (), 169 
cf rectangle {) , 171 
cfrelidev () , 171 
cfreqinpO, 171 
cfrsttodefs (), 171 
cf sampinp () , 172 
cf saspsouflags (), 172 
cfsdefatrigassoc () , 172 
cf sdrawmode () , 172 
cf serrwarnmk ( ) , 172 
cf sf lusheventqu ( ) , 172 
cf sgldrawmode (), 172 
cfsinitval (), 172 
cf supsig ( ) , 173 
cf svalrange () , 173 
cftext 0 , 173 
cftextalign (), 173 
cftextbundix ( ) , 173 
cftextcolor {) , 173 
cf t extf ont ix ( ) , 173 
cf textprec ( ) , 173 
cftrackoff (), 173 
cftrackon () , 173 
cfvdcext 0 , 174 
cfvdmtext (), 174 
CGI Tool, 15 



CGI type definitions, 109 thru 1 19 
CGI with Pixwins, 143 thru 152 
close_cgi_jpw ( ) , 145 
close^w_cgi {), 145 
example, 150 

open_cgi_canvas { ) , 144 
open_cgi_pw ( ) , 144 
open_pw_cgi ( ) , 143 
using CGIPW, 145 thru 146 
cgicbind.h, 177 
cgi constant s-h, 109 
cgidef s .h, 110 
Character Expansion Factor 
C function, 72 
FORTRAN function, 161 



Character Height 
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Character Height, continued 
C function, 72 
FORTRAN function, 161 
Character Orientation 
C function, 73 
FORTRAN function, 161 
Character Path 
C function, 74 
FORTRAN function, 161 
Character Set Index 
C function, 71 
FORTRAN function, 161 
Character Spacing 
C function, 72 
FORTRAN function, 161 
character_expansion_factor 0 , 72 
character_height ( ) , 72 
character_orientation () , 73 
character_j>ath ( ) , 74 
character_set_index () , 71 
character_spacing () , 72 
Circle 

C function, 40 
FORTRAN function, 161 
circle () , 40 
Circular Arc 3 pt 
C function, 42 
FORTRAN function, 161 
Circular Arc 3pt Close 
C function, 42 
FORTRAN function, 161 
Circular Arc Center 
C function, 40 
FORTRAN function, 162 
Circular Arc Center Close 
C function, 41 
FORTRAN function, 162 
circular_arc_3pt ( ) , 42 
circular_arc_3pt_close () , 42 
circular_arc_center () , 40 
circular_arc_center_close () , 41 
Clear Control 

C function, 22 
FORTRAN function, 162 
Clear View Surface 
C function, 21 
FORTRAN function, 162 
clear_cont rol ( ) , 22 
clear_view_surface ( ) , 21 
Clip Indicator 

C function, 20 
FORTRAN function, 162 
CUp Rectangle 
C function, 21 
FORTRAN function, 162 
clip_indicator (), 20 
clip_rectangle (), 21 
clipping, 18, 20 
Close a CGI Pixwin, 145 
Close CGI (SunCGI Extension) 

C function, 18 



Close CGI (SunCGI Extension), continued 
FORTRAN function, 162 
Close Pixwin CGI, 145 
Close View Surface (SunCGI Extension) 

C function, 17 
FORTRAN function, 162 
close_cgi () , 18 
close_cgi_pw ( ) , 145 
close_pw_cgi (), 145 
close_vws 0 , 17 
color 

attributes, 76 thru 77 
color_table () , 76 
Color Lookup Table 
C function, 76 
FORTRAN function, 162 
col or_t able () , 76 
conical output primitives, 36 thru 44 
control error, 124 

coordinate definition error, 124 thru 125 

D 

data type definitions, 109 thru 119 
Deactivate View Surface (SunCGI Extension) 
C function, 17 
FORTRAN function, 162 
deactivate_vws (), 17 
Define Bundle Index (SunCGI Extension) 

C function, 59 
FORTRAN fimction, 163 
def ine_bundle_index () , 59 
device coordinates, see screen space 
Device Viewport 
C function, 20 
FORTRAN function, 163 
device_viewport () , 20 
Disable Events 
C function, 99 
FORTRAN fimction, 163 
disable_e vents (), 99 
Disjoint Polyline 
C fimction, 37 
FORTRAN fimction, 163 
dis joint_polyline () , 37 
dissociate { ) , 89 
Dissociate 

C function, 89 
FORTRAN fimction, 163 
drawing mode, 5, 44, 50 thru 52 

inc[uire_drawing_mode ( ) , 52 
set_drawing_mode () , 51 
set_global_drawing_mode () , 51 

E 

ellipse 0 , 43 
Ellipse 

C fimction, 43 
FORTRAN fimction, 163 
Elliptical Arc 

C fimction, 43 
FORTRAN fimction, 164 
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Elliptical Arc Close 
C function, 43 
FORTRAN function, 163 
elliptical_arc () , 43 
elliptical_arc_close () ,43 
Enable Events 

C function, 96 
FORTRAN function, 164 
enable_e vents () , 96 
error, 22 

control, 22, 124 

coordinate definition, 124 thru 125 
implonentation dq)endent, 131 
input, 129 thru 131 
output attribute, 125 thru 127 
output primitive, 128 thru 129 
possible causes of visual, 131 thru 133 
state, 123 thru 124 
error message 

EARCPNCI, 128 
EARCPNEL, 128 
EBADCOLX, 126 
EBADDATA, 130 
EBADFABX, 126 
EBADLINX, 125 
EBADMRKX, 126 
EBADRCTD, 124 
EBADSIZE, 126 
EBADTXTX, 127 
EBBDTBDI, 125 
EBDCHRIX, 127 
EBDVIEWP, 125 
EBDWIDTH, 126 
EBTBUNDL, 125 
EBTUNDEF, 125 
ECELLATS, 128 
ECELLPOS, 128 
ECELLTLS, 128 
ECEXFOOR, 127 
ECHHTLEZ, 127 
ECHRUPVZ, 127 
ECINDXLZ, 126 
ECLIPTOL, 125 
ECLIPTOS, 125 
ECOLRNGE, 127 
EGPLISFL, 128 
EIAEVNEN, 130 
EINAIIMP, 129 
EINASAEX, 129 
EINDALIN, 129 
EINDINIT, 129 
EINDNOEX, 129 
EINECHON, 130 
EINEINCP, 130 
EINENOTO, 130 
EINERVWS, 130 
EINETNSO, 130 
EINEVNEN, 130 
EINNECHO, 130 
EINNTASD, 129 
EINQALTL, 124 
EINQOVFL, 131 
EINTRNEX, 129 



error message, continued 
EMAXVSOP, 124 
EMEMSPAC, 131 
ENMPTSTL, 128 
ENOPATNX, 127 
ENOTCCPW, 131 
ENOTCGCL, 123 
ENOTCGOP, 123 
ENOTCSTD, 131 
ENOTOPOP, 124 
ENOTVSAC, 123 
ENOTVSOP, 123 
ENOWSTYP, 124 
EPATARTL, 126 
EPATITOL, 127 
EPATSZTS, 126 
EPGMTHPT, 128 
EPLMTWPT, 128 
EPXNOTCR, 129 
ESTRSIZE, 131 
ESTYLLEZ, 126 
ETXTFLIN, 127 
EVALOVWS, 129 
EVDCSDIL, 125 
EVSIDINV, 124 
EVSISACT, 124 
EVSNOTOP, 124 
EVSNTACT, 124 
NO_ERROR, 123 
event queue, 89, 97 

input functions, 94 thru 99 
status, 99 

F 

fill area attributes, 64 thru 65 
Fill Area Bundle Index 
C function, 64 
FORTRAN function, 164 
Fill Color 

C function, 65 
FORTRAN function, 164 
fill_area_bundle_index () , 64 
f ill_color ( ) , 65 
Fixed Font (SunCGI Extension) 

C function, 73 
FORTRAN function, 164 
f ixed_f ont ( ) , 73 
Flush Event Queue 
C function, 97 
FORTRAN function, 164 
f lush_event_queue ( ) , 97 
FORTRAN function, 165, 169 
cfactvws 0, 160 
cfaptext 0, 160 
cfassoc 0 , 160 
cf await ev () , 160 
cfbtblpatarr 0, 160 
cfbtblpatsouarr 0 , 161 
cfbtblsouarr ( ) , 161 
cfcellarr () , 161 
cf charexpf ac ( ) , 161 
cf charheight ( ) , 161 
cf charorient ( ) , 161 
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FORTRAN function, continued 
cf charpath ( ) , 161 
cf charsetix () , 161 
cf charspacing 0 , 161 
cfcircarccent (), 162 
cf circarccentcl {) , 162 
cfcircarcthree (), 161 
cf circarcthreecl (), 161 
cfcircle () , 161 
cf clipind ( ) , 162 
cfcliprect (), 162 
cfclosecgi {), 162 
cfclosevws 0, 162 
cfclrcont {), 162 
cfclrvws 0, 162 
cf cotable () , 162 
cfdaevents {), 163 
cfdeactvws (), 162 
cfdefbundix (), 163 
cf devvpt ( ) , 163 
cfdissoc 0, 163 
cfdpolyline (), 163 
cf elliparc ( ) , 164 
cfelliparccl (), 163 
cf ellipse (), 163 
cfenevents {), 164 
cffixedfont (), 164 
cff lareabundix {), 164 
cfflcolor 0, 164 
cff lusheventqu {), 164 
cf get last reqinp {) , 164 
cfhardrst {) , 164 
cfhatchixO, 164 
cfinitlidO, 164 
cfinitreqO, 165 
cfint style (), 169 
cflncolor 0 , 169 
cf Inendstyle ( ) , 169 
cf Inspecmode ( ) , 169 
cf Inwidth ( ) , 169 
cf mkcolor ( ) , 169 
cfmksize (), 169 
cf nOcspecmode ( ) , 169 
cf mktype ( ) , 169 
cfopencgi (), 169 
cfopenvws (), 170 
cfpatfillcolor 0, 170 
cfpatix 0 , 170 
cfpatrefpt (), 170 
cfpatsize 0, 170 
cf pattable ( ) , 170 
cf perimcolor ( ) , 170 
cfperimspecmode () , 170 
cfperimtype (), 170 
cf perimwidth ( ) , 170 
cf pixarr { ) , 170 
cf polygon (), 171 
cf polyline (), 171 
cfpolylnbundix 0, 171 
cf polymarker 0 , 171 
cfpolymkbundixO, 171 
cfppolygon ( ) , 170 
cfqasf s 0 , 165 
cfqbtbltalign (), 165 



FORTRAN function, continued 
cf qcellarr ( ) , 165 
cfqdevclass () , 165 
cfqdevidO, 165 
cfqdrawmode () , 165 
cf qevque ( ) , 165 
cfqflareaatts (), 166 
cfqinpcaps (), 166 
cfqlidcaps (), 167 
cfqlidstate () , 167 
cfqlidstatelis () , 166 
cfqlnatts () , 167 
cfqmkatts () , 167 
cf gout cap () , 167 
cfqoutf unset ( ) , 167 
cfqpatatts (), 167 
cfqphyscsys () , 168 
cfqpixarr () , 168 
cfcftextatts () , 168 
cf qtextext ( ) , 168 
cfqtrigcaps {) , 168 
cf qtrigstate ( ) , 169 
cf qvdctype ( ) , 169 
cf rectangle () , 171 
cfrelidev () , 171 
cf reqinp 0, 171 
cfrsttodef s {) , 171 
cf sampinp () , 172 
cf saspsouflags, 172 
cfsdefatrigassoc () , 172 
cfsdrawmode () , 172 
cf serrwarnmk ( ) , 172 
cf sf lusheventqu 0 , 172 
cf sgldrawmode (), 172 
cf sinitval ( ) , 172 
cfsupsig 0, 173 
cf svalrange () , 173 
cftext 0 , 173 
cftextalign () , 173 
cf textbundix ( ) , 173 
cftext color ( ) , 173 
cftextf ontix ( ) , 173 
cf textprec ( ) , 173 
cftrackof f ( ) , 173 
cftrackon () , 173 
cfvdcext 0, 174 
cfvdmtext () , 174 
FORTRAN interface 

function definitions, 160/Ar« 174 
programming hints, 155 thru 156 
using FORTRAN, 155 

G 

geometrical ou^ut primitives, 35, 35 thru 44 
Get Last Requested Input 
C function, 98 
FORTRAN function, 164 
get_last_requested_input () , 98 
global polygon list, 37, 38 
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H 

Hard Reset 

C function, 21 
FORTRAN function, 164 
hard_reset () , 21 
Hatch Index 

C function, 67 
FORTRAN function, 164 
hatch_index ( ) , 67 

I 

IC.STROKE, 88 

implementation dqjendent error, 131 

include files, 4 

initialize 

activate_vws ( ) , 17 
close_cgi (), 18 
close_vws 0, 17 
deactivate_vws (), 17 
open_cgi { ) , 12 
open_vws () , 13 
SunCG/, 12 
Initialize LID 

C function, 86 
FORTRAN function, 164 
initialize_lid () , 86 
Initiate Request 
C function, 94 
FORTRAN function, 165 
initiate_request () , 94 
input device, 86 
capabilities, 28 

iiutialization functions, 86 thru 92 
status, 99 

input error, 129 thru 131 
input functions 

associate () , 88 
await_event 0,96 
disable_e vents (), 99 
dissociate () , 89 
enable_events ( ) , 96 
f lush_event_queue 0 , 97 
get_last_requested_input () , 98 
initialize_lid ( ) , 86 
initiate_request () , 94 
inquire_event_queue_state () , 100 
inquire_lid_state () , 100 
inquire_lid_state_list {) , 99 
incjuire_trigger_state () , 100 
release_input_device () , 87 
request_input ( ) , 93 
sample_input ( ) , 98 

selective_flush_of_event_queue () , 97 
set_default_trigger_associations () , 88 
set_initial_value () , 89 
set_valuator_range () , 90 
track_off () , 91 
track_on ( ) , 90 
Inquire Aspect Source Flags 
C function, 80 
FORTRAN function, 165 
Inquire Bitblt Alignments 



Inquire Bitblt Alignments, continued 
C function, 50 
FORTRAN function, 165 
Inquire Cell Array 
C function, 49 
FORTRAN function, 165 
Inquire Device Bitmap 
C function, 50 
FORTRAN function, 165 
Inquire Device Class 
C function, 26 
FORTRAN function, 165 
Inquire Device Identification 
C function, 26 
FORTRAN function, 165 
Inquire Drawing Mode 
C fimction, 52 
FORTRAN function, 165 
Inquire Event Queue State 
C function, 100 
FORTRAN function, 165 
Inquire Fill Area Attributes 
C function, 78 
FORTRAN function, 166 
Inquire Input Capabilities 
C function, 28 
FORTRAN function, 166 
Inquire LID Capabilities 
C function, 29 
FORTRAN function, 167 
Inquire LID State 
C function, 100 
FORTRAN function, 167 
Inquire LID State List 
C function, 99 
FORTRAN function, 166 
Inquire Line Attributes 
C function, 78 
FORTRAN function, 167 
Inquire Marker Attributes 
C function, 78 
FORTRAN function, 167 
Inquire Output Capabilities 
C function, 28 
FORTRAN function, 167 
Inquire Output Function Set 
C function, 27 
FORTRAN function, 167 
Inquire Pattern Attributes 
C function, 79 
FORTRAN function, 167 
Inquire Physical Coordinate System 
C function, 26 
FORTRAN function, 168 
Inquire Pixel Array 
C function, 49 
FORTRAN function, 168 
Inquire Text Attributes 
C function, 79 
FORTRAN function, 168 
Inquire Text Extent 
C function, 45 
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Inquire Text Extent, continued 
FORTRAN function, 168 
Inquire Trigger Capabilities 
C function, 30 
FORTRAN function, 168 
Inquire Trigger State 
C function, 100 
FORTRAN function, 169 
Inquire VDC Type 
C function, 27 
FORTRAN function, 169 
inquire_aspect_source_flags (), 80 
inquire_bitblt_alignments () , 50 
inquire_cell_array ( ) , 49 
inquire_device_bitmap { ) , 50 
inquire_device_class () , 26 
inquire_device_identif ication () , 26 
inquire_drawing_mode () , 52 
inc[uire_event_queue_state () , 100 
inquire_f ill_area_attributes () , 78 
inquire_input_capabilities () , 28 
inquire_lid_capabilities () , 29 
inc[uire_lid_state () , 100 
inquire_lid_state_list () , 99 
inquire_line_attributes () , 78 
inquire_marker_attributes () , 78 
inquire_output_capabilities (), 28 
inquire_output_function_set () , 27 
inquire_pattern_attributes () , 79 
inquire_j>hysical_coordinate_system 0 , 26 
inquire^ixel_array () , 49 
inquire_text_attributes ( ) , 79 
inquire_text_extent () , 45 
inquire_trigger_capabilities () , 30 
inquire_trigger_state () , 100 
inquire_vdc_type ( ) , 27 
interface negotiation, 25 thru 31 

inquire_device_class () , 26 
inquire_device_identif ication () , 26 
inquire_input_capabilities {) , 28 
inquire_lid_capabilities (), 29 
inquire_output_capabilities () , 28 
inquire_output_function_set () , 27 
inquire_physical_coordinate_system () , 26 
inquire_trigger_capabilities () , 30 
inquire_vdc_type () , 27 
Interior Style 

C function, 64 
FORTRAN function, 169 
interior_style (), 64 

L 

line attributes, 60 thru 62 
color, 62 
endstyle, 61 

polyline bundle index, 60 
type, 60 
width, 62 

width specification mode, 61 
Line Color 



Line Color, continued 
C function, 62 
FORTRAN function, 169 
Line Endstyle (SunCGI Extension) 

C function, 61 
FORTRAN function, 169 
Line Type 

C function, 60 
FORTRAN function, 169 
Line Width 

C function, 62 
FORTRAN function, 169 
Line Width Specification Mode 
C function, 61 
FORTRAN function, 169 
line_color 0 , 62 
line_endstyle 0,61 
line_type () , 60 
line_width ( ) , 62 

line_width_specif ication_mode () , 61 
linking SunCGI, 3 
lint library, 4 
logical input device, 6 

M 

Marker Color 

C function, 64 
FORTRAN function, 169 
Marker Size 

C function, 63 
FORTRAN function, 169 
Marker Size Specification Mode 
C function, 63 
FORTRAN function, 169 
Marker Type 

C function, 63 
FORTRAN function, 169 
marker_color { ) , 64 
marker_size () , 63 

markar_size_specif ication_mode ( ) , 63 
marker_type 0 , 63 

N 

negotiation functions, 5 
non-retained windows, 14 
NORMAL_VWSURF, 13, 17 

o 

Open a CGI Canvas, 144 
Open a CGI Pixwin, 144 
Open CGI (SunCGI Extension) 

C function, 12 
FORTRAN function, 169 
Open Pixwin CGI, 143 
Open View Surface (SunCGI Extension) 

C function, 13 
FORTRAN function, 170 
open_cgi () , 12 
open_cgi_canvas () , 144 
open_cgi_pw ( ) , 144 
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open_pw_cgi ( ) , 143 
open_vws () , 13 
output attribute error, 125 thru 127 
output primitive error, 128 thru 129 
output primitives, 3, 5, 35 thru 52 
append_text { ) , 45 
bitblt_pattern_array ( ) , 47 
bitblt_patterned_source_array () , 48 
bitblt_source_array {) , 47 
cell_array () , 46 
circle ( ) , 40 
circular_arc_3pt ( ) , 42 
circular_arc_3pt_close () , 42 
circular_arc_center () , 40 
circular_arc_center_close ( ) , 41 
conical, 36 thru 44 
dis joint_polyline () , 37 
drawing mode, 50 thru 52 
ellipse 0 , 43 
elliptical_arc ( ) , 43 
elliptical_arc_close () ,43 
geometrical, 35 thru 44 
inquire_bitblt_alignments () , 50 
inquire_cell_array ( ) , 49 
inquire_device_bitmap ( ) , 50 
inquire_drawing_mode () , 52 
inquire__pixel_array () , 49 
incpiire_text_extent () , 45 
partial_polygon () , 38 
pixel_array ( ) , 46 
polygon () , 37 
polygonal, 35, 35 thru 40 
polyline () , 36 
polymarker ( ) , 37 
raster, 44 thru 50 
rectangle () , 40 
set_drawing_mode ( ) , 51 
set_global_drawing_mode ( ) , 51 
text ( ) , 44 
vdm_text (), 44 

P 

Partial Polygon 
C function, 38 
FORTRAN function, 170 
partial_polygon () , 38 
pattern attributes, 65 thru 68 
fill color, 68 
hatch index, 67 
pattern index, 67 
reference pwint, 68 
size, 68 
table, 67 
Pattern Index 

C function, 67 
FORTRAN function, 170 
Pattern Reference Point 
C function, 68 
FORTRAN function, 170 
Pattern Size 

C function, 68 
FORTRAN function, 170 
Pattern Table 



PatternTable, continued 
C function, 67 
FORTRAN function, 170 
Pattern with Fill Color (SunCGI Extension) 

C function, 68 
FORTRAN function, 170 
pattern_index () , 67 
pattern_ref erence_point (> , 68 
pattern_size ( ) , 68 
pattern_table () , 67 
pattern_with_f ill_color () , 68 
perimeter attributes, 69 thru 70 
color, 70 
endstyle, 69 
type, 69 
visibility, 65 
width, 69 

width specification mode, 70 
Perimeter Color 
C function, 70 
FORTRAN function, 170 
Perimeter Type 
C function, 69 
FORTRAN function, 170 
Perimeter Width 
C function, 69 
FORTRAN function, 170 
Perimeter Width Specification Mode 
C function, 70 
FORTRAN function, 170 
perimeter_color 0 , 70 
perimeter_type ( ) , 69 
perimeter_width ( ) , 69 

perimeter_width_specif ication_mode () , 70 
Pixel Array 

C function, 46 
FORTRAN function, 170 
pixel_array ( ) , 46 
Pixwins with CGI, 143 thru 152 
example, 150 
functions, 146 thru 148 
using CGIPW, 145 thru 146 
polygon () , 37 
Polygon 

C function, 37 
FORTRAN function, 171 
polygonal primitives, 35, 35 thru 40 
polyline () , 36 
Polyline 

C function, 36 
FORTRAN function, 171 
Polyline Bundle Index 
C function, 60 
FORTRAN fimction, 171 
polyline_bundle_index () , 60 
polymarker ( ) , 37 
Polymarker 

C function, 37 
FORTRAN function. 171 
polymarker attributes, 62 thru 64 
bundle index, 62 
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polymarker attributes, continued 
color, 64 
size, 63 

size specification mode, 63 
type, 63 

Polymarker Bundle Index 
C function, 62 
FORTRAN function, 171 
polymarker_bundle__index () , 62 

R 

raster primitives, 35, 44 thru 50 
rectangle ( ) , 40 
Rectangle 

C function, 40 
FORTRAN function, 171 
Release Input Device 
C function, 87 
FORTRAN function, 171 
release_input_device () , 87 
Request Input 

C function, 93 
FORTRAN function, 171 
request register, 94, 98 
request_input ( ) , 93 
Reset to Defaults 
C function, 21 
FORTRAN function, 171 
reset_to_defaults () , 21 
retained windows, 14 

s 

Sample Input 

C function, 98 
FORTRAN function, 172 
sample_input () , 98 
screen space, 5, 18, 20 
Selective Flush of Event Queue 
C function, 97 
FORTRAN function, 172 
selective_flush_of_event_queue () , 97 
Set Aspect Source Flags 
C function, 58 
FORTRAN function, 172 
Set Default Trigger Associations 
C function, 88 
FORTRAN function, 172 
Set Drawing Mode 
C function, 51 
FORTRAN function, 172 
Set Error Warning Mask 
C function, 22 
FORTRAN function, 172 
Set Global Drawing Mode (SunCGI Extension) 

C function, 51 
FORTRAN function, 172 
Set Initial Value 
C function, 89 
FORTRAN function, 172 
Set Up SIGWINCH (SunCGI Extension) 

C function, 24 



Set Up SIGWINCH (SunCGI Extension), continued 
FORTRAN function, 173 
Set VALUATOR Range 
C function, 90 
FORTRAN function, 173 
set_aspect_source_flags {) , 58 
set_default_trigger_associations () , 88 
set_drawing_mode () , 51 
set_error_warning_mask () , 22 
set_global_drawing_mode () , 51 
set_initial_value ( ) , 89 
set_up_sigwinch ( ) , 24 
set_valuator_range () , 90 
signal trapping, 23, 25 
SIGWINCH, 5, 23 
solid object attributes, 64 thru 70 

f ill_area_bundle_index ( ) , 64 
f ill_color 0 , 65 
interior_style ( ) , 64 
state error, 123 thru 124 
status inquiries, 99 thru 101 
synchronous input functions, 92 thru 94 

T 

Text 

C function, 44 
FORTRAN function, 173 
Text Alignment 
C function, 74 
FORTRAN function, 173 
text attributes, 70 thru 76 

character expansion factor, 72 
character height, 72 
character orientation, 73 
character path, 74 
character set index, 71 
character spacing, 72 
fixed font, 73 
text alignment, 74 
text bundle index, 70 
text color, 73 
text font index, 71 
text precision, 71 
Text Bundle Index 
C function, 70 
FORTRAN function, 173 
Text Color 

C function, 73 
FORTRAN function, 173 
Text Font Index 
C function, 71 
FORTRAN function, 173 
Text Precision 
C function, 71 
FORTRAN function, 173 
text_alignment () , 74 
text ( ) , 44 

text_bundle_index ( ) , 70 
text_color ( ) , 73 
text_f ont_index ( ) , 71 
text_precision () , 71 
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Track Off 

C function, 91 
FORTRAN function, 173 
Track On 

C function, 90 
FORTRAN function, 173 
track_off (), 91 
track_on () , 90 
tracking, 90 thru 92 
trigger, 6, 28, 88 
equabilities, 30 

interaction with STROKE device, 88 
status, 99 

type definitions, 109 thru 119 

u 

unsupported CGI functions, 105 thru 106 
using SunCGI, 3 

V 

VDC Extent 

C function, 18 
FORTRAN function, 174 
VDC space, 5, 18 
vdc_extent () , 18 
VDMText 

C function, 44 
FORTRAN function, 174 
vdm_text ( ) , 44 
view surface, 11, 15 
active, 5 
clearing, 21 
default states, 16 
initializing, 13 
multiple, 5, 13 

view surface control, 18 thru 23 
clear_control () , 22 
clear_view_surf ace ( ) , 21 
clip_indicator ( ) , 20 
clip_rectangle ( ) , 21 
device_viewport () , 20 
hard_reset () , 21 
reset_to_defaults () , 21 
set_error_warning_mask () , 22 
vdc_extent ( ) , 18 
visual error, 131 thru 133 

w 

windows 

nonretained, 13 
retained, 13 

world coordinates, see VDC space 
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